api-description.yaml

openapi: "3.0.3"
info:
  title: "Cryptify API"
  description: "This is the cryptify server that manages encrypted files."
  version: "1.0.0"
servers:
  - url: http://localhost:8000
    description: Development server
tags:
- name: "Health"
  description: "Health check"
- name: "File upload"
  description: "Upload files"
- name: "File download"
  description: "Download files"
- name: "Usage"
  description: "Upload usage quotas"
paths:
  /health:
    get:
      tags:
        - "Health"
      summary: "Health check endpoint"
      operationId: "health"
      responses:
        "200":
          description: "Service is healthy"
          content:
            text/plain:
              schema:
                type: "string"
                example: "OK"
  /fileupload/init:
    post:
        tags:
        - "File upload"
        summary: "Initialize multipart file upload"
        operationId: "initFileUpload"
        requestBody:
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - recipient
                  - mailContent
                  - mailLang
                  - confirm
                properties:
                  recipient:
                    type: "string"
                    format: "email"
                    example: "recipient@example.com"
                    description: "Email address of the recipient"
                  mailContent:
                    type: "string"
                    example: "Here is your encrypted file"
                    description: "Content to include in the email"
                  mailLang:
                    type: "string"
                    enum: ["EN", "NL"]
                    example: "EN"
                    description: "Email language (EN or NL)"
                  confirm:
                    type: "boolean"
                    example: true
                    description: "Whether to send a confirmation email to the sender"
        responses:
          "200":
            description: "Successful operation"
            headers:
                cryptifytoken:
                  description: "Identifies the initial version of the file to be uploaded. Needs to be passed into the file part upload request."
                  required: true
                  schema:
                    type: "string"
            content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    uuid:
                      type: "string"
                      format: "uuid"
                      description: "Unique identifier for the file upload"
  /fileupload/{uuid}:
    put:
      tags:
      - "File upload"
      summary: "Upload a file part"
      operationId: "uploadFilePart"
      parameters:
      - in: "header"
        name: "cryptifytoken"
        description:
          "Identifies the version of the upload file parts. Part of the header from the last fileupload response."
        schema:
          type: "string"
        required: true
      - in: "header"
        name: "Content-Range"
        description:
          "Which offset of a file is sent, example: `bytes 200-1000/*`."
        schema:
          type: "string"
        required: true
      - in: "path"
        name: "uuid"
        required: true
        description: "The unique identifier received when initializing file upload."
        schema:
          type: "string"
          format: "uuid"
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: "string"
              format: "binary"
      responses:
        "200":
          description: "Successful operation."
          headers:
            cryptifytoken:
              required: true
              schema:
                description: "Identifies the new version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "409":
          description: "Server file parts cryptifytoken differs from cryptifytoken in request."
          headers:
            cryptifytoken:
              required: true
              schema:
                description:
                  "Identifies the version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description: "Partially uploaded file does not exist."
        "413":
          description: "The upload exceeds the per-upload size limit (5 GB)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadTooLarge"

  /fileupload/finalize/{uuid}:
    post:
      tags:
      - "File upload"
      summary: "Finalize multipart file upload and send mail to recipient"
      operationId: "finalizeFileUpload"
      parameters:
      - in: "header"
        name: "Content-Range"
        description:
          "Indicates the final file size: `bytes */1073741824`."
        schema:
          type: "string"
        required: true
      - in: "path"
        name: "uuid"
        description: "The unique identifier received when initializing file upload."
        required: true
        schema:
          type: "string"
          format: "uuid"
      responses:
        "200":
          description: "Successful operation"
        "409":
          description: "Server file parts cryptifytoken differs from cryptifytoken in request"
          headers:
            cryptifytoken:
              required: true
              schema:
                description: "Identifies the version of the upload file parts. Needs to be passed into the next file part upload request."
                type: "string"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description: "Partially upload file does not exist."
        "413":
          description: "The sender has exceeded the rolling 14-day upload limit (15 GB)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadTooLarge"
        "422":
          description: "Data is missing to form complete file."

  /usage:
    get:
      tags:
      - "Usage"
      summary: "Get rolling upload usage for a sender email"
      description:
        "Returns the bytes uploaded by the given email address in the last 14 days,
        together with the applicable limits. Frontends use this to warn the user
        before they hit the limit."
      operationId: "getUsage"
      parameters:
      - in: "query"
        name: "email"
        description: "The sender email address to query."
        required: true
        schema:
          type: "string"
          format: "email"
      responses:
        "200":
          description: "Usage information for the given email."
          content:
            application/json:
              schema:
                type: "object"
                required:
                  - email
                  - used_bytes
                  - limit_bytes
                  - window_days
                  - per_upload_limit_bytes
                properties:
                  email:
                    type: "string"
                    format: "email"
                  used_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Bytes uploaded by this email in the rolling window."
                  limit_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Rolling-window upload limit in bytes (15 GB)."
                  window_days:
                    type: "integer"
                    description: "Length of the rolling window in days."
                  per_upload_limit_bytes:
                    type: "integer"
                    format: "int64"
                    description: "Maximum size of a single upload in bytes (5 GB)."
                  resets_at:
                    type: "string"
                    format: "date-time"
                    nullable: true
                    description:
                      "RFC-3339 timestamp at which the oldest recorded upload
                      falls out of the rolling window, partially freeing quota.
                      Null if the sender has no recorded uploads."

  /filedownload/{uuid}:
    get:
      tags:
      - "File download"
      summary: "Download a file"
      operationId: "downloadFile"
      parameters:
      - in: "path"
        name: "uuid"
        required: true
        description: "The unique identifier received when initializing file upload."
        schema:
          type: "string"
          format: "uuid"
      responses:
        "200":
          description: "Successful operation."
          content:
            application/cryptify+octet-stream:
              schema:
                type: "string"
                format: "binary"
        "400":
          description: "One of the input parameters is incorrect."
          content:
              application/json:
                schema:
                  type: "object"
                  properties:
                    message:
                      type: "string"
        "404":
          description: "Uploaded file does not exist."

components:
  schemas:
    PayloadTooLarge:
      type: "object"
      required:
        - error
        - limit
        - used_bytes
        - limit_bytes
      properties:
        error:
          type: "string"
          description: "Human-readable explanation of which limit was hit."
        limit:
          type: "string"
          enum:
            - "per_upload"
            - "rolling_window"
          description: "Which limit tripped the 413 response."
        used_bytes:
          type: "integer"
          format: "int64"
          description:
            "Bytes already attributed to the sender in the relevant window.
            For per_upload, this is the bytes already written for the current
            upload before the rejected chunk."
        limit_bytes:
          type: "integer"
          format: "int64"
          description: "The limit value in bytes."