{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-upload-session-schema.json",
  "title": "UploadSession",
  "description": "An open upload, and every URL needed to fill it.\n\nTwo things are deliberately not here.\n\nThe R2 object KEY. It is inside each presigned URL and cannot not be, since\nan S3 presigned URL is a signed PATH. What is refused is publishing it as a\nFIELD: a field is a stable, structured handle a client would build on and we\ncould never withdraw, whereas the URL is a fifteen-minute capability for one\nobject the caller was already granted. Nothing cross-tenant is disclosed\neither way; the uuids in that path are the caller's own.\n\nThe DOCUMENT ID. There is no document until the bytes land, only an\nintention to create one, and publishing an id for a row that may never be\nfilled invites a customer to store it and then poll something that never\nstarts. It arrives on the operation's `resource` at complete time, which is\nthe first moment it means anything.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-uploads-api-openapi.yml#/components/schemas/UploadSession",
  "properties": {
    "uploadId": {
      "type": "string",
      "title": "Uploadid",
      "description": "Public identifier for this upload session, `upl_` followed by 32 hex characters. Use it to presign a part and to complete the upload."
    },
    "partSize": {
      "type": "integer",
      "title": "Partsize",
      "description": "Size in bytes of every part except the last. Split the file on exactly this boundary or the assembled object will not match."
    },
    "totalParts": {
      "type": "integer",
      "title": "Totalparts",
      "description": "How many parts to upload. Always at least 1: a small file is a one-part upload rather than a separate code path."
    },
    "parts": {
      "items": {
        "$ref": "#/$defs/UploadPartLink"
      },
      "type": "array",
      "title": "Parts",
      "description": "One presigned URL per part, in order."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "title": "Expiresat",
      "description": "When the whole SESSION expires (RFC 3339), which is much later than any individual part URL. Past this, storage discards the parts and the upload has to start again."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "uploadId",
    "partSize",
    "totalParts",
    "parts",
    "expiresAt"
  ],
  "$defs": {
    "UploadPartLink": {
      "properties": {
        "partNumber": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Partnumber",
          "description": "Which part this URL is for. Parts are numbered from 1 and must be uploaded under the number given here."
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "Presigned URL to `PUT` this part's bytes to, directly to storage. No bytes pass through the Vaquill API. Keep the `ETag` the response returns."
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "title": "Expiresat",
          "description": "When this part URL stops working (RFC 3339). Re-sign an expired part with `uploads.presignPart`; parts already uploaded stay valid."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "partNumber",
        "url",
        "expiresAt"
      ],
      "title": "UploadPartLink",
      "description": "Where to PUT one part, and how long that stays true.\n\n`expiresAt` is on every part rather than on the session, because a large\nupload outlives a single signature: a client re-signs the parts it has not\nfinished through `uploads.presignPart` and keeps the ones it has."
    }
  }
}