Create an upload ticket
const url = 'https://files.centralcodestation.com/api/v1/tenants/example/applications/example/uploads';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"IMG_5913.jpg","size":4194304,"mime_type":"image/jpeg","folder_id":"01J9Z6R2M3N4P5Q6R7S8T9V0W1","owner_id":"u-ana","tags":["beach"],"custom":{"post_id":"123"},"visibility":"application","external_ref":"post:123"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://files.centralcodestation.com/api/v1/tenants/example/applications/example/uploads \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "IMG_5913.jpg", "size": 4194304, "mime_type": "image/jpeg", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "owner_id": "u-ana", "tags": [ "beach" ], "custom": { "post_id": "123" }, "visibility": "application", "external_ref": "post:123" }'Checks the name, the declared type and size against the application’s policy and the quota, reserves the size, and answers the signed URL (put, up to 64 MiB) or the first 100 part URLs (multipart). file_id is known at once. Needs edit on the folder.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The Identity Server tenant id.
The Identity Server application id: a tenant application, or (platform clients) the client’s own platform application.
Header Parameters
Section titled “Header Parameters”Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Bytes; checked again at completion (422 size_mismatch).
Hex SHA-256; signed into single PUTs and verified by processing.
object
A named upload policy of the application; unknown names fall back to the default (policy_applied).
Machine tokens: the user the file belongs to.
Machine tokens: the user you act for (audit).
object
object
Who gets file.ready besides the owner.
rename picks “name (1).ext” instead of answering 409 name_conflict.
Example
{ "name": "IMG_5913.jpg", "size": 4194304, "mime_type": "image/jpeg", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "owner_id": "u-ana", "tags": [ "beach" ], "custom": { "post_id": "123" }, "visibility": "application", "external_ref": "post:123"}Responses
Section titled “Responses”Created.
object
Known at once: store it in your own record.
put only: PUT the whole body here.
Send exactly these headers with the PUT, and nothing else.
object
The first 100 part URLs; POST …/parts for the rest.
object
GET only: the parts the store holds (resume from the first missing one).
object
Example
{ "upload_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4E", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "version_no": 1, "status": "open", "policy_applied": "default", "method": "put", "url": "https://upload.files.example/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D?signature=...", "headers": { "Content-Type": "image/jpeg" }, "part_size": null, "parts_total": null, "parts": null, "expires_at": "2026-10-22T10:12:33.120Z"}Error. error is one of: invalid_request, invalid_name.
object
Stable snake_case error code.
Example
{ "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: invalid_token.
object
Stable snake_case error code.
Example
{ "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: not_tenant_member, no_application_access, tenant_not_available, insufficient_scope, client_context_mismatch, files_access_not_granted, missing_action, tenant_suspended, folder_managed.
object
Stable snake_case error code.
Example
{ "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: application_not_found, not_found, folder_not_found.
object
Stable snake_case error code.
Example
{ "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: name_conflict, folder_busy, file_trashed, idempotency_key_reused.
object
Stable snake_case error code.
Example
{ "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: file_too_large, quota_exceeded.
object
Stable snake_case error code.
Example
{ "status_code": 413, "error": "file_too_large", "message": "The declared size is above the application's `max_file_size_bytes`, the upload policy's, the tenant's or the platform cap.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: type_not_allowed, taxonomy_value_invalid, public_visibility_disabled.
object
Stable snake_case error code.
Example
{ "status_code": 422, "error": "type_not_allowed", "message": "The declared or detected type is outside the application's `allowed_types` (or the upload policy's).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: rate_limited.
object
Stable snake_case error code.
Example
{ "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}Error. error is one of: identity_unavailable, storage_unavailable.
object
Stable snake_case error code.
Example
{ "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z"}default
Section titled “default”Error: see error for the code.
object
Stable snake_case error code.
Example
{ "status_code": 403, "error": "invalid_request", "message": "This client is not bound to this tenant/application", "path": "/api/v1/tenants/t1/applications/a1/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D"}