# Uploading a file

Preferred workflow: POST the file to /api/uploads. Do not choose or invent a bucket path; the server assigns one.

Authentication: make FILES_API_KEY available through the agent platform's secret or environment mechanism and send Authorization: Bearer $FILES_API_KEY. Never paste the key into a URL, publish it, or include it in the returned answer.

Upload a file:
  curl --globoff -sS -X POST "https://as3.yachint.in/api/uploads" \
    -H "Authorization: Bearer $FILES_API_KEY" \
    -H "X-Filename: final-report.pdf" \
    -H "Content-Type: application/pdf" \
    --data-binary @final-report.pdf

X-Filename is required and must be a filename, not a path. Use a normal ASCII filename for the simplest workflow. For Unicode or reserved characters, percent-encode the filename's UTF-8 bytes exactly once (for example, résumé.pdf becomes r%C3%A9sum%C3%A9.pdf). Content-Length is required (curl supplies it for --data-binary). Maximum size is 100 MiB. PDF, Markdown, TXT, and XML are first-class report formats; other file types are accepted.

The server chooses a UTC monthly path such as agent-uploads/2026/07/A-K7M9Q2DX_final-report.pdf. A successful response is HTTP 201 JSON with agentUploadId, originalFilename, requestedKey, key, size, contentType, and viewUrl. Return viewUrl to the user (and optionally agentUploadId for search).

Automatic uploads are atomic and never overwrite existing content. A rare generated-ID collision returns retryable HTTP 409. Advanced callers may choose a path with PUT /api/objects/{key}. To deliberately replace a prior agent upload, PUT to its exact returned key and send X-Allow-Overwrite: true. Replacement uses the current ETag so concurrent changes return retryable HTTP 409.

Retry discipline: retry only when the JSON response contains retryable: true. Use exponential backoff and stop after 3 retries. Do not retry authentication, validation, or file-size errors. Upload multiple files sequentially unless the user explicitly requests otherwise.

Humans must sign in to open viewUrl. Human-readable instructions: https://as3.yachint.in/upload
OpenAPI 3.1 contract: https://as3.yachint.in/openapi.json