{
  "openapi": "3.1.0",
  "info": {
    "title": "SecuFiler API",
    "version": "1.0.3"
  },
  "servers": [
    {
      "url": "https://public-api.secumail.nl",
      "description": "Production"
    },
    {
      "url": "https://test-public-api.secumail.nl",
      "description": "Acceptance"
    }
  ],
  "tags": [
    {
      "name": "SecuFiler",
      "description": "SecuFiler secure file transfer operations."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/secufiler": {
      "post": {
        "tags": [
          "SecuFiler"
        ],
        "operationId": "createTransfer",
        "summary": "Create a transfer and initiate the multipart upload",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sender",
                  "recipients",
                  "filename",
                  "filesize"
                ],
                "additionalProperties": false,
                "properties": {
                  "sender": {
                    "type": "string",
                    "format": "email",
                    "description": "Sender email address.",
                    "examples": [
                      "system@customer.example"
                    ]
                  },
                  "recipients": {
                    "type": "array",
                    "description": "One or more recipient email addresses.",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "examples": [
                      [
                        "bob@partner.example",
                        "carol@partner.example"
                      ]
                    ]
                  },
                  "filename": {
                    "type": "string",
                    "examples": [
                      "archive.zip"
                    ]
                  },
                  "filesize": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 1,
                    "maximum": 5497558138880,
                    "description": "Total size of the file in bytes. Used to compute `partSize` /\n`partCount`. Maximum 5 TiB (5497558138880 bytes).",
                    "examples": [
                      10737418240
                    ]
                  },
                  "subject": {
                    "type": "string",
                    "description": "Subject shown in the notification email.",
                    "examples": [
                      "Quarterly export"
                    ]
                  },
                  "message": {
                    "type": "string",
                    "description": "Message body shown in the notification email.",
                    "examples": [
                      "Please find the file attached."
                    ]
                  },
                  "nta7516": {
                    "type": "boolean",
                    "default": false,
                    "description": "Apply NTA 7516 (Dutch secure healthcare email) handling. Honoured\nonly when the sender's domain is a SecuMailer customer certified for\nNTA 7516; forced to false otherwise."
                  }
                }
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal — sender, one recipient, filename, filesize",
                  "value": {
                    "sender": "system@customer.example",
                    "recipients": [
                      "bob@partner.example"
                    ],
                    "filename": "archive.zip",
                    "filesize": 10737418240
                  }
                },
                "full": {
                  "summary": "Multiple recipients with subject, message and 2FA",
                  "value": {
                    "sender": "system@customer.example",
                    "recipients": [
                      "bob@partner.example",
                      "carol@partner.example"
                    ],
                    "filename": "archive.zip",
                    "filesize": 10737418240,
                    "subject": "Quarterly export",
                    "message": "Please find the file attached.\nRegards, Finance",
                    "nta7516": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Transfer created and multipart upload initiated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "nonce",
                    "key",
                    "uploadId",
                    "partSize",
                    "partCount",
                    "completeUrl"
                  ],
                  "properties": {
                    "nonce": {
                      "type": "string",
                      "format": "uuid",
                      "examples": [
                        "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b"
                      ]
                    },
                    "key": {
                      "type": "string",
                      "examples": [
                        "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b/archive.zip"
                      ]
                    },
                    "uploadId": {
                      "type": "string",
                      "examples": [
                        "2~Zt1p0Yx9c0bWq3n8sample-upload-id"
                      ]
                    },
                    "partSize": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Size in bytes of every part except the last. Slice the file into\n`partCount` parts of this size (the final part holds the remainder).",
                      "examples": [
                        536870912
                      ]
                    },
                    "partCount": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 10000,
                      "description": "Number of parts to upload (`partNumber` runs 1..partCount).",
                      "examples": [
                        20
                      ]
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Expiry of the presigned URLs (UTC). Complete the upload before this time.",
                      "examples": [
                        "2026-07-02T12:00:00Z"
                      ]
                    },
                    "completeUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Presigned `CompleteMultipartUpload` URL. `POST` the ordered\n`CompleteMultipartUpload` XML (PartNumber + ETag list) here to\nassemble the object and trigger delivery.",
                      "examples": []
                    },
                    "abortUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Presigned `AbortMultipartUpload` URL. `DELETE` here to discard the\nupload and release any stored parts (e.g. on a failed upload).",
                      "examples": []
                    }
                  }
                },
                "examples": {
                  "created": {
                    "value": {
                      "nonce": "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b",
                      "key": "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b/archive.zip",
                      "uploadId": "2~Zt1p0Yx9c0bWq3n8sample-upload-id",
                      "partSize": 536870912,
                      "partCount": 20,
                      "expiresAt": "2026-07-02T12:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing request parameters — e.g. missing sender/recipients/\nfilename/filesize, malformed email, unknown nonce/uploadId, or SecuFiler\nnot activated for the customer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "missingSender": {
                    "value": {
                      "message": "[Bad Request] Missing sender"
                    }
                  },
                  "unknownUpload": {
                    "value": {
                      "message": "[Bad Request] Unknown nonce or uploadId"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "invalidApiKey": {
                    "value": {
                      "message": "[Unauthorized] Invalid API key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The sender's domain is not an eligible SecuMailer customer, or SecuFiler\nis not activated for it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "notCustomer": {
                    "value": {
                      "message": "The sender is not a SecuMailer client"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Requested `filesize` exceeds the 5 TiB maximum.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "tooLarge": {
                    "value": {
                      "message": "[Payload Too Large] filesize exceeds the 5 TiB maximum"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server-side failure.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "initiateFailed": {
                    "value": {}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/secufiler/part": {
      "post": {
        "tags": [
          "SecuFiler"
        ],
        "operationId": "getPartUploadUrl",
        "summary": "Get a presigned URL for one upload part",
        "description": "Upload the part with a single HTTP `PUT` of that slice of the file to the\nreturned `url`, then read the `ETag` response header — you will need the\n`{ partNumber, etag }` pairs to complete the upload.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "nonce",
                  "uploadId",
                  "partNumber"
                ],
                "additionalProperties": false,
                "properties": {
                  "nonce": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Transfer id from the create response.",
                    "examples": [
                      "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b"
                    ]
                  },
                  "uploadId": {
                    "type": "string",
                    "examples": [
                      "2~Zt1p0Yx9c0bWq3n8sample-upload-id"
                    ]
                  },
                  "partNumber": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000,
                    "description": "Part number (1..partCount).",
                    "examples": [
                      1
                    ]
                  }
                }
              },
              "examples": {
                "partRequest": {
                  "value": {
                    "nonce": "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b",
                    "uploadId": "2~Zt1p0Yx9c0bWq3n8sample-upload-id",
                    "partNumber": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned URL for the requested part.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "partNumber",
                    "url"
                  ],
                  "properties": {
                    "partNumber": {
                      "type": "integer",
                      "description": "The part number this URL is for.",
                      "examples": [
                        1
                      ]
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "examples": []
                    }
                  }
                },
                "examples": {
                  "partUrl": {
                    "value": {
                      "partNumber": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing request parameters — e.g. missing sender/recipients/\nfilename/filesize, malformed email, unknown nonce/uploadId, or SecuFiler\nnot activated for the customer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "missingSender": {
                    "value": {
                      "message": "[Bad Request] Missing sender"
                    }
                  },
                  "unknownUpload": {
                    "value": {
                      "message": "[Bad Request] Unknown nonce or uploadId"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "invalidApiKey": {
                    "value": {
                      "message": "[Unauthorized] Invalid API key"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server-side failure.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "examples": [
                        "[Bad Request] Missing sender"
                      ]
                    }
                  }
                },
                "examples": {
                  "initiateFailed": {
                    "value": {}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid or missing request parameters — e.g. missing sender/recipients/\nfilename/filesize, malformed email, unknown nonce/uploadId, or SecuFiler\nnot activated for the customer.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "examples": [
                    "[Bad Request] Missing sender"
                  ]
                }
              }
            },
            "examples": {
              "missingSender": {
                "value": {
                  "message": "[Bad Request] Missing sender"
                }
              },
              "unknownUpload": {
                "value": {
                  "message": "[Bad Request] Unknown nonce or uploadId"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "examples": [
                    "[Bad Request] Missing sender"
                  ]
                }
              }
            },
            "examples": {
              "invalidApiKey": {
                "value": {
                  "message": "[Unauthorized] Invalid API key"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The sender's domain is not an eligible SecuMailer customer, or SecuFiler\nis not activated for it.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "examples": [
                    "[Bad Request] Missing sender"
                  ]
                }
              }
            },
            "examples": {
              "notCustomer": {
                "value": {
                  "message": "The sender is not a SecuMailer client"
                }
              }
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "Requested `filesize` exceeds the 5 TiB maximum.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "examples": [
                    "[Bad Request] Missing sender"
                  ]
                }
              }
            },
            "examples": {
              "tooLarge": {
                "value": {
                  "message": "[Payload Too Large] filesize exceeds the 5 TiB maximum"
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Server-side failure.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "examples": [
                    "[Bad Request] Missing sender"
                  ]
                }
              }
            },
            "examples": {
              "initiateFailed": {
                "value": {}
              }
            }
          }
        }
      }
    },
    "schemas": {
      "CreateTransferRequest": {
        "type": "object",
        "required": [
          "sender",
          "recipients",
          "filename",
          "filesize"
        ],
        "additionalProperties": false,
        "properties": {
          "sender": {
            "type": "string",
            "format": "email",
            "description": "Sender email address.",
            "examples": [
              "system@customer.example"
            ]
          },
          "recipients": {
            "type": "array",
            "description": "One or more recipient email addresses.",
            "minItems": 1,
            "items": {
              "type": "string",
              "format": "email"
            },
            "examples": [
              [
                "bob@partner.example",
                "carol@partner.example"
              ]
            ]
          },
          "filename": {
            "type": "string",
            "examples": [
              "archive.zip"
            ]
          },
          "filesize": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 5497558138880,
            "description": "Total size of the file in bytes. Used to compute `partSize` /\n`partCount`. Maximum 5 TiB (5497558138880 bytes).",
            "examples": [
              10737418240
            ]
          },
          "subject": {
            "type": "string",
            "description": "Subject shown in the notification email.",
            "examples": [
              "Quarterly export"
            ]
          },
          "message": {
            "type": "string",
            "description": "Message body shown in the notification email.",
            "examples": [
              "Please find the file attached."
            ]
          },
          "nta7516": {
            "type": "boolean",
            "default": false,
            "description": "Apply NTA 7516 (Dutch secure healthcare email) handling. Honoured\nonly when the sender's domain is a SecuMailer customer certified for\nNTA 7516; forced to false otherwise."
          }
        }
      },
      "CreateTransferResponse": {
        "type": "object",
        "required": [
          "nonce",
          "key",
          "uploadId",
          "partSize",
          "partCount",
          "completeUrl"
        ],
        "properties": {
          "nonce": {
            "type": "string",
            "format": "uuid",
            "examples": [
              "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b"
            ]
          },
          "key": {
            "type": "string",
            "examples": [
              "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b/archive.zip"
            ]
          },
          "uploadId": {
            "type": "string",
            "examples": [
              "2~Zt1p0Yx9c0bWq3n8sample-upload-id"
            ]
          },
          "partSize": {
            "type": "integer",
            "format": "int64",
            "description": "Size in bytes of every part except the last. Slice the file into\n`partCount` parts of this size (the final part holds the remainder).",
            "examples": [
              536870912
            ]
          },
          "partCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "description": "Number of parts to upload (`partNumber` runs 1..partCount).",
            "examples": [
              20
            ]
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry of the presigned URLs (UTC). Complete the upload before this time.",
            "examples": [
              "2026-07-02T12:00:00Z"
            ]
          },
          "completeUrl": {
            "type": "string",
            "format": "uri",
            "description": "Presigned `CompleteMultipartUpload` URL. `POST` the ordered\n`CompleteMultipartUpload` XML (PartNumber + ETag list) here to\nassemble the object and trigger delivery.",
            "examples": []
          },
          "abortUrl": {
            "type": "string",
            "format": "uri",
            "description": "Presigned `AbortMultipartUpload` URL. `DELETE` here to discard the\nupload and release any stored parts (e.g. on a failed upload).",
            "examples": []
          }
        }
      },
      "PartUrlRequest": {
        "type": "object",
        "required": [
          "nonce",
          "uploadId",
          "partNumber"
        ],
        "additionalProperties": false,
        "properties": {
          "nonce": {
            "type": "string",
            "format": "uuid",
            "description": "Transfer id from the create response.",
            "examples": [
              "8f14e45f-ceea-467d-9f0a-1c2d3e4f5a6b"
            ]
          },
          "uploadId": {
            "type": "string",
            "examples": [
              "2~Zt1p0Yx9c0bWq3n8sample-upload-id"
            ]
          },
          "partNumber": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "description": "Part number (1..partCount).",
            "examples": [
              1
            ]
          }
        }
      },
      "PartUrlResponse": {
        "type": "object",
        "required": [
          "partNumber",
          "url"
        ],
        "properties": {
          "partNumber": {
            "type": "integer",
            "description": "The part number this URL is for.",
            "examples": [
              1
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "examples": []
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "examples": [
              "[Bad Request] Missing sender"
            ]
          }
        }
      }
    }
  }
}