Files

Create file upload session

Creates a direct-to-storage upload session. This endpoint does not upload the file bytes. Use the returned instructions as follows:

  1. Send a separate PUT request to upload.url using upload.method and every header in upload.headers. Do not send the API Bearer token to that URL; the signed URL is the temporary upload credential.
  2. After the PUT succeeds, call POST /files/uploads/{upload_id}/complete with this response's uploadId.
  3. Use the completed response's fileId as a file input in later API calls.

For large files, storageMethod may be multipart; in that case, PUT each item in parts and pass the returned ETags to the complete endpoint. If the session was created with sha256, the API verifies the stored object checksum before completion; multipart completions must include actualSha256. Use Idempotency-Key so retries return the same reservation and signed URL.

post/api/v1/files/uploads

Request

  • Base URL: https://api.studio.kaitoi.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.studio.kaitoi.io/api/v1/files/uploads
  • Auth: HTTP bearer

Headers

Idempotency-Keystring nullable
authorizationstring nullable

Request body

filenamestring required

Original filename.

contentTypestring

Media type to attach to the uploaded object.

sizeBytesinteger required

Exact file size in bytes. This reserves storage quota before bytes are uploaded.

sha256string nullable

Optional lowercase hex SHA-256. Recommended so the API can verify end-to-end object integrity before completing the upload.

externalIdstring nullable

Developer-provided external file identifier.

externalUserIdstring nullable

Developer-provided end-user identifier.

externalWorkspaceIdstring nullable

Developer-provided workspace/team identifier.

Example request

{
  "contentType": "image/png",
  "externalId": "asset_123",
  "externalUserId": "user_789",
  "externalWorkspaceId": "team_456",
  "filename": "input.png",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "sizeBytes": 12345
}

Response

Upload session and signed upload instructions.

uploadIdstring required

Upload session id. Use this with POST /files/uploads/{uploadId}/complete.

fileIdstring required

File id reserved for this upload. It becomes readable after completion.

externalIdstring nullable

Developer-provided external file identifier.

externalUserIdstring nullable

Developer-provided end-user identifier.

externalWorkspaceIdstring nullable

Developer-provided workspace/team identifier.

storageMethod'single_part' | 'multipart' | 'proxied_relay' required

Upload strategy selected by the API. For single_part and proxied_relay, send one PUT to upload.url. For multipart, send each PUT in parts, then include the returned ETags when completing the upload.

expiresAtstring date-time required

Upload session expiration timestamp.

partSizeBytesinteger nullable

Target multipart part size in bytes.

partCountinteger nullable

Number of multipart parts to upload.

Example response

{
  "expiresAt": "2026-05-24T13:00:00+00:00",
  "externalId": "asset_123",
  "externalUserId": "user_789",
  "externalWorkspaceId": "team_456",
  "fileId": "2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png",
  "storageMethod": "single_part",
  "upload": {
    "headers": {
      "Content-Type": "image/png"
    },
    "method": "PUT",
    "url": "https://storage.example.com/signed-upload-url"
  },
  "uploadId": "upl_8d7f7f7e1dd64d3e8e2d0d2e4b3c9a1f"
}

Changes

No recorded changes to this operation across all 1 revision of this API.