Skip to main content
POST
JavaScript
When a payload is too big to inline, you do not POST the bytes to Cadenya. You ask for a place to put them, upload them directly to storage, and hand the resulting upload_id to whatever needs the data.
filename, contentType, and sizeBytes are all required. sizeBytes is a string, because it is a 64-bit integer.

The three steps

1. Create the upload. The response carries info.uploadUrl, a short-lived signed URL, and info.uploadUrlExpiresAt. The status is UPLOAD_STATUS_PENDING: the row exists, the bytes do not. 2. PUT the bytes to that URL. Upload straight to storage, not through the Cadenya API. Match the Content-Type you declared.
The URL points at object storage, so this call never touches Cadenya. When it succeeds, the upload moves to UPLOAD_STATUS_COMPLETE. 3. Reference the upload_id. Hand the ID to the resource that needs the payload, such as a memory entry too large to inline:

You cannot reference an upload before its bytes land

This is the guard to code around. Referencing an upload still in UPLOAD_STATUS_PENDING is a 400, with the reason spelled out:
So the order is fixed: create, PUT, then reference. A reference that fails with this message means the PUT has not finished, or never happened. Poll GET /uploads/{id} for UPLOAD_STATUS_COMPLETE before you use the ID if your upload and reference are decoupled.

The status lifecycle

An EXPIRED upload cannot be revived. Create a new one and PUT again. uploadUrlExpiresAt on the create response tells you how long you have.

Get an upload

Poll for UPLOAD_STATUS_COMPLETE before referencing.

Create a memory entry

uploadId for an entry too big to inline.

Set tool call content

Large tool results follow the same big-payload pattern.

Create an objective

Where large input data can reference an upload.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json
metadata
object
required

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object
required

Response

OK

A handle representing a single file upload flow. Clients call CreateUpload to receive a short-lived presigned URL, PUT the file directly to object storage, then reference the upload by id when creating or updating resources that accept binary content.

Uploads are one-shot: once consumed by a creating or updating resource the upload transitions to UPLOAD_STATUS_CONSUMED and cannot be reused. Unused uploads expire and are garbage-collected.

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

spec
object
required
info
object
required