Skip to content

create_file_upload_ticket

Create a short-lived ticket to upload one local file over HTTPS.

Prefer this to upload_file for a file on the machine where you run shell commands, such as a photo or a PDF: no file bytes pass through tool arguments, so the upload does not depend on generating base64. Compute the file’s lowercase SHA-256 and exact byte count locally (for example sha256sum photo.jpg and wc -c < photo.jpg) and pass only those values; the file may be at most 50 MB. Then, before expiresAt (at most 10 minutes), set UPLOAD_TOKEN to uploadToken and UPLOAD_URL to uploadUrl from this result, without printing the token, and run:

curl --fail-with-body \
-H "Authorization: Bearer $UPLOAD_TOKEN" \
-F "file=@photo.jpg;type=image/jpeg" \
"$UPLOAD_URL"

Set type= to the file’s real content type; the server rejects content types outside its allow-list and rejects SVG payloads. The response is the stored file’s metadata: store its id in a record’s file field to attach the file. The ticket works once, for exactly that file in that application: the first upload returns 201, an identical retry returns 200 with the same file, and a 409 site_upload_in_progress means retry after Retry-After.

{
"additionalProperties": false,
"properties": {
"application_id": {
"format": "uuid",
"type": "string"
},
"file_sha256": {
"description": "Lowercase hex SHA-256 of the file, computed locally.",
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"file_size_bytes": {
"description": "Exact file byte count, excluding multipart framing.",
"maximum": 52428800,
"minimum": 1,
"type": "integer"
}
},
"required": [
"application_id",
"file_sha256",
"file_size_bytes"
],
"type": "object"
}
{
"additionalProperties": false,
"properties": {
"archiveSha256": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"archiveSizeBytes": {
"minimum": 1,
"type": "integer"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"maxArchiveBytes": {
"const": 52428800,
"type": "integer"
},
"method": {
"const": "POST"
},
"multipartField": {
"const": "file"
},
"ticketId": {
"description": "Non-secret audit correlation identifier; it cannot authorize.",
"format": "uuid",
"type": "string"
},
"uploadToken": {
"description": "Short-lived bearer for that one upload; returned only here.",
"type": "string",
"writeOnly": true
},
"uploadUrl": {
"description": "Canonical HTTPS URL of the application's file ticket-upload route.",
"format": "uri",
"type": "string"
}
},
"required": [
"ticketId",
"uploadUrl",
"method",
"multipartField",
"uploadToken",
"expiresAt",
"archiveSha256",
"archiveSizeBytes",
"maxArchiveBytes"
],
"type": "object"
}