Upload a file in one multipart request; returns a file id usable as attachmentFileIds.
Uploads a file in one multipart request and returns its id, ready to pass as attachmentFileIds on a run. Unlike the Console flow there is no presign/confirm round trip: the server holds the bytes, so the file is Stored the moment this returns.
Limits are the platform storage bounds — 25 MB, and the storage content-type allowlist (PNG, JPEG, WebP, GIF, PDF, plain text, CSV, and audio as MP3, MP4, WAV, WebM, Ogg or FLAC). **Note these are wider than what a run can consume:** attachmentFileIds accepts images (PNG/JPEG/WebP/GIF, 20 MB), audio (MP3/MP4/WAV/WebM/Ogg/FLAC, 20 MB) and PDF documents (20 pages, 20 MB) — at most 8 attachments per run, a PDF counting as one however many pages it has. A file outside those bounds uploads successfully here and is refused, with a message naming what was wrong, if it is later attached to a run.
An attached PDF is read by the agent's read_document tool, which rasterizes every page and reads them in one call; it needs an active **Vision** capability binding, and a scanned image-only PDF works as well as one with a text layer.
**Retention:** delete a file you no longer need with DELETE /v1/files/{id} — your client can delete any file it uploaded here, attached to a run or not. Otherwise a file is erased along with the run it is attached to when that run's end user is erased by an organisation admin; a file that is never attached to a run is not reachable by end-user erasure, so track its id and delete it.
If your organisation turned **Keep files sent by API keys** off (Console → API keys) before the upload, Amy deletes the file itself as soon as every run it is attached to has ended — completed or failed — or an hour after upload if no run uses it. The run still lists the attachment, but its content answers 404, a later turn of the same conversation cannot read it again, and a failed run whose files were discarded cannot be retried (its retryable is false). The setting at upload time decides; changing it later does not affect files already uploaded.
Request
No parameters and no body — just the key.
Example
shell
curl -X POST https://api.askamy.co.za/v1/files \
-H "X-Api-Key: $AMY_API_KEY"