{"openapi":"3.1.0","info":{"title":"Agentic Upload API","version":"1.0.0","description":"Upload files and return authenticated human view links."},"servers":[{"url":"https://as3.yachint.in"}],"paths":{"/api/uploads":{"post":{"summary":"Upload a file without choosing a storage path (preferred)","description":"The server assigns an agent-uploads/YYYY/MM path and creates the object atomically. Do not send X-Allow-Overwrite. Provision the bearer token through the agent platform's secret or environment mechanism; never put it in a URL or returned answer. Retry only responses containing retryable: true, with exponential backoff and at most 3 retries. Do not retry authentication, validation, or size errors; upload files sequentially unless explicitly instructed otherwise.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Filename","in":"header","required":true,"description":"A single filename, not a path. Plain ASCII is preferred. Percent-encode the filename's UTF-8 bytes exactly once for Unicode or reserved characters (for example, résumé.pdf becomes r%C3%A9sum%C3%A9.pdf).","schema":{"type":"string"}},{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":0,"maximum":104857600}},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Stored in the server-assigned namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticUploadResult"}}}},"400":{"description":"Filename or request validation failed; code and hint describe how to correct filename failures","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}]}}}},"401":{"$ref":"#/components/responses/Error"},"409":{"description":"Generated-key collision; retry the request with exponential backoff (maximum 3 retries)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConditionalError"}}}},"411":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/api/objects/{key}":{"put":{"summary":"Create or deliberately replace an agent upload","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"allowReserved":true,"description":"Slash-delimited requested key for creates; exact previously returned key for overwrites. Encode each path segment. The final key limit is 1024 UTF-8 bytes: create requests are limited to 1013 UTF-8 bytes because the server adds an 11-byte prefix, while overwrite keys may use all 1024 bytes.","schema":{"type":"string"}},{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":0,"maximum":104857600}},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Allow-Overwrite","in":"header","required":false,"description":"Set to true only when replacing an existing exact agent-prefixed key. The server conditionally replaces its current ETag; missing keys return 404 and concurrent changes return 409.","schema":{"type":"string","const":"true"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"description":"Overwrite target does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyError"}}}},"409":{"description":"Create-key collision, unavailable ETag, or concurrent overwrite change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConditionalError"}}}},"411":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}},"get":{"summary":"Check an actual object key","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Existence result","content":{"application/json":{"schema":{"type":"object","required":["exists","size"],"properties":{"exists":{"type":"boolean"},"size":{"type":["integer","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/api/objects/_index/rebuild":{"post":{"summary":"Start search-index reconciliation","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Started or already running","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["started","already-running"]}}}}}},"401":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"UploadResult":{"type":"object","required":["agentUploadId","requestedKey","key","size","contentType","viewUrl"],"properties":{"agentUploadId":{"type":"string","pattern":"^A-[0-9A-HJKMNP-TV-Z]{8}$"},"requestedKey":{"type":"string"},"key":{"type":"string"},"size":{"type":"integer"},"contentType":{"type":"string"},"viewUrl":{"type":"string","format":"uri"}}},"AutomaticUploadResult":{"allOf":[{"$ref":"#/components/schemas/UploadResult"},{"type":"object","required":["originalFilename"],"properties":{"originalFilename":{"type":"string"}}}]},"ValidationError":{"type":"object","required":["error","code","hint"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["FILENAME_REQUIRED","FILENAME_ENCODING_INVALID","INVALID_FILENAME","FILENAME_TOO_LONG"]},"hint":{"type":"string"}}},"KeyError":{"type":"object","required":["error","key"],"properties":{"error":{"type":"string"},"key":{"type":"string"}}},"ConditionalError":{"type":"object","required":["error","key"],"properties":{"error":{"type":"string","enum":["object already exists","object cannot be safely overwritten","object changed during overwrite"]},"key":{"type":"string"},"retryable":{"type":"boolean"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}