Sign in

Initiate Attachment Upload

Initiates (or deduplicates) an upload of a file attached to a session. If the exact content is already stored for this (session ID, file path), the response has alreadyExists: true and no upload is needed. Otherwise, PUT the file bytes to the returned uploadUrl, then call the commit endpoint. Re-initiating an existing (session ID, file path) with new content updates the attachment in place on commit.

post/attachments

Request body

sessionIdstring required

The session ID the attachment belongs to. Matches the session.id emitted on OTel spans, which is how attachments are joined to traces and records.

filePathstring required

The logical file path of the attachment (e.g. the path the agent wrote on disk). Together with the session ID it identifies the attachment: re-uploading the same path in the same session updates the existing attachment in place.

sha256string required

Lowercase hex SHA-256 of the file content.

sizeBytesinteger required

Size of the file in bytes.

contentTypestring required

MIME type of the file.

filenamestring

Display filename. Defaults to none.

metadataobject

Arbitrary metadata to store with the attachment.

Example request

{
  "sessionId": "c59e5bd0-e5eb-4bf0-a08a-01f7e8f712c7",
  "filePath": "/tmp/report.pdf",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "sizeBytes": 482133,
  "contentType": "application/pdf",
  "filename": "report.pdf"
}

Response

Upload initiated (or content already stored). If alreadyExists is false, PUT the bytes to uploadUrl and then commit.

idstring uuid required

The ID of the Attachment.

alreadyExistsboolean required

True if this exact content is already stored for this (session, file path) — no upload is needed and no upload URL is returned.

uploadUrlstring nullable required

Signed URL to PUT the file bytes to. Null when alreadyExists is true.

uploadMethod'PUT' | 'null' nullable required

HTTP method to use with uploadUrl.

expiresAtstring nullable required

ISO 8601 expiry of uploadUrl.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Changes