Files

Send a file into a run; read one back out.

1. Upload

One multipart request, one part named file. There is no presign/confirm round trip on this surface — the server takes the bytes, and the file is stored by the time the call returns.

shell 
curl -X POST https://api.askamy.co.za/v1/files \
  -H "X-Api-Key: $AMY_API_KEY" \
  -F "file=@lab-report.pdf"
# → 201 {"id":"3f0c…","filename":"lab-report.pdf","contentType":"application/pdf","sizeBytes":184320}

Uploads accept up to 25 MB and the platform content-type allowlist: PNG, JPEG, WebP, GIF, PDF, plain text, CSV, and audio as MP3, MP4, WAV, WebM, Ogg or FLAC.

What a bad upload answers:

  • 415 — the request was not multipart/form-data.
  • 400 — there is no part named file, or Amy will not store the file (a type outside the allowlist, or over the size limit); detail says which.
  • 413 — the whole request is over the transport ceiling: 25 MB plus a small allowance for the multipart envelope.
  • 403 — your plan's storage allowance, files.storage_mb, has no room for the file; see Usage.
  • 502 / 503 — storage failed to take the bytes (502: nothing was stored, upload again), or file storage is not available (503, see Retry-After where it is sent).

Each of those is a ProblemDetails body; see Errors.

2. Attach it to a run

request 
curl -X POST https://api.askamy.co.za/v1/agents/amy/runs/await \
  -H "X-Api-Key: $AMY_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise the findings in this report.",
    "attachmentFileIds": ["3f0c…"]
  }'

What a run will consume is narrower than what upload accepts: images (PNG, JPEG, WebP, GIF), audio (MP3, MP4, WAV, WebM, Ogg, FLAC) and PDFs, each up to 20 MB, and a PDF up to 20 pages. At most 8 attachments go on one run; a PDF counts as one however many pages it has. A file outside those bounds uploads fine and is refused when attached — a 400 that names what was wrong. Reading a PDF needs an active Vision capability on your organisation. Attachments belong on the streamed and awaited start calls; a submitted run ignores attachmentFileIds.

3. Read back what the run produced

GET /v1/runs/{runId} lists the run's attachments, each with a fileId. An attachment is whatever the run produced — a generated image, a spoken reply, or a real .xlsx workbook. Each row carries its own contentType, so you never have to guess from the filename. A storage fault while streaming the bytes is a 502. Fetch the bytes with:

shell 
curl -OJ https://api.askamy.co.za/v1/runs/01936c2f-…/files/8a21…/content \
  -H "X-Api-Key: $AMY_API_KEY"

There is a second, separate read path — GET /v1/runs/{runId}/workspace-files/{interactionId}/content — for files a run wrote with file tools. It is not used on hosted Amy: every id there is a 404. To read what a run produced, use the attachment route above.

4. Delete what you uploaded

When you are done with a file, delete it. That removes the bytes and frees the storage it counted against your organisation.

shell 
curl -X DELETE https://api.askamy.co.za/v1/files/3f0c… \
  -H "X-Api-Key: $AMY_API_KEY"
# → 204

You can delete any file your API client uploaded through POST /v1/files, with any of that client's keys — a rotated key included. Every other file id is a 404: another client's upload, a file a run generated, a file uploaded in the Console, and a file uploaded before this endpoint existed. A 502 means storage refused the delete; nothing was removed, so retry. A 503 means file storage is unavailable.

A file attached to a run can be deleted too. The run still lists the attachment, but its content route answers 404, and a later run that reads the file no longer finds it — so delete once you are done with the run.

Scoping and retention

  • A file must be attached to the run you are asking about. A file id that belongs to your account but not to that run is a 404, not a 403.
  • A file attached to a run is erased with that run when an organisation Admin erases its end user. A file that is uploaded and never attached is not reachable that way — track its id and delete it yourself.
  • If your product keeps its own copy, an organisation Admin can turn Keep files sent by API keys off (Console → API keys). Each file your keys upload is then deleted once every run that reads it has ended, or an hour after upload if no run used it. Files sent before the switch went off are deleted only when the Admin asks: Also delete the files already kept counts them first, then deletes exactly that count.