Skip to main content

​
Attach files to a task

Do this when the agent needs to read a file you supply — a CSV to analyse, a PDF to summarise, a log to search. Do not do this for files that should persist across tasks; those belong in workspace or project storage, which the agent reaches through a different path. Uploading is a two-step: stage the bytes, then reference the staging ref in the create-task body. There is no multipart task-create endpoint.

​
Prerequisites

  • An API key with access to the workspace.
  • The agent id you will run the task against.
  • The file’s SHA-256 digest, in both hex and base64. You compute this before uploading; the object store verifies against it.

​
Choose an upload path

Both return a ref of the form staging/{id}/{filename}, and the create-task endpoint treats them identically.

​
Steps

​
1. Compute the digest

​
2. Mint a presigned upload URL

The request takes the digest as lowercase hex.

​
3. PUT the bytes

The digest is bound into the signature, so the x-amz-checksum-sha256 header is mandatory and must carry the base64 digest. Content-Type must match what you presigned with.
The object store rejects a body that does not hash to the declared digest, so a truncated or swapped upload fails here rather than reaching the agent. Alternative — server-proxied upload. One call, no digest arithmetic:

​
4. Create the task with the ref

The server HEADs each ref to resolve its verified digest, size, and content type, then server-side copies it into the task workspace at inputs/attachments/{filename}. The agent is told about the files by relative path in its prompt, so it can read them without being asked to fetch anything. Two attachments with the same basename are disambiguated deterministically: report.csv and report-1.csv.

​
Verify

List the task’s files and confirm the attachment landed under inputs/attachments/:
If the path is present with the size you uploaded, the agent can read it.

​
Troubleshooting

403 or SignatureDoesNotMatch on the PUT. The x-amz-checksum-sha256 header was omitted, or carries hex instead of base64, or the Content-Type sent differs from the one presigned. All three are part of the signature. Re-mint the URL if you need to change the content type. 404 “attachment ref not found” at task creation. The presigned URL expired before the PUT completed (expires_in is 3600 seconds), or the PUT failed and was not retried. Mint a fresh URL and upload again — refs are not reusable across a failed upload. 422 “attachment integrity digest is unavailable”. The staged object carries neither the sha256 metadata nor an S3-native checksum. This happens when bytes were written to the staging key by something other than these two endpoints. Do not work around it; re-upload through a supported path. 413 on upload or on task creation. The per-file limit is 256 MiB, enforced at both the presign step and the server-proxied upload. A 413 at task creation instead means the workspace’s total quota would be exceeded by the attach. 422 “Invalid attachment ref”. Refs must begin with staging/. A workspace file path is not an attachment ref; upload it with purpose=attachment to get one. The task dispatches but the agent says it cannot find the file. Check that the descriptor path starts with inputs/attachments/ in the artifacts listing. The prompt only advertises attachments under that exact prefix, so a file committed elsewhere in the workspace is present but not announced.