{"openapi":"3.1.0","info":{"title":"Ultra Agent Exchange API","version":"4.0.0","description":"Agent-first asset exchange primitives: upload, resolve, grant, fetch, and delete."},"servers":[{"url":"https://ultra-dev.egomonk.com"}],"paths":{"/api/upload":{"post":{"summary":"Upload a file and create a share","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"ttl":{"type":"integer","minimum":30},"max_uses":{"type":"integer","minimum":1,"description":"Open-link byte fetch limit. Defaults to 1."},"auth_mode":{"type":"string","enum":["open","agent"]},"allowed_agent_ids":{"type":"string"},"policy_metadata":{"type":"string","description":"JSON object encoded as a string."}}}}}},"responses":{"201":{"description":"Upload created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}}}}},"/api/import-url":{"post":{"summary":"Import a remote URL and create a share","description":"Fetches an http(s) URL server-side after SSRF checks, redirect revalidation, byte caps, and timeout caps. Imported objects become normal Ultra file shares.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"mimeType":{"type":"string"},"ttl":{"type":"integer","minimum":30},"maxUses":{"type":"integer","minimum":1},"authMode":{"type":"string","enum":["open","agent"]},"allowedAgentIds":{"type":"array","items":{"type":"string"}},"policyMetadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"URL imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}},"400":{"description":"Invalid or blocked import URL"},"413":{"description":"Import exceeds byte cap"},"502":{"description":"Upstream fetch or redirect failure"},"504":{"description":"Import timed out"}}}},"/api/upload/multipart/init":{"post":{"summary":"Initialize native Turbo multipart upload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","size"],"properties":{"filename":{"type":"string"},"size":{"type":"integer","minimum":1},"mimeType":{"type":"string"},"ttl":{"type":"integer","minimum":30},"maxUses":{"type":"integer","minimum":1},"authMode":{"type":"string","enum":["open","agent"]},"allowedAgentIds":{"type":"array","items":{"type":"string"}},"policyMetadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Multipart upload initialized"}}}},"/api/upload/multipart/part":{"post":{"summary":"Upload a native Turbo multipart part","responses":{"200":{"description":"Part accepted"},"404":{"description":"Multipart upload not found"}}}},"/api/upload/multipart/complete":{"post":{"summary":"Complete native Turbo multipart upload","responses":{"201":{"description":"Upload completed as a normal Ultra share"},"404":{"description":"Multipart upload not found"}}}},"/api/upload/multipart/abort":{"post":{"summary":"Abort native Turbo multipart upload","responses":{"200":{"description":"Multipart upload aborted"}}}},"/api/upload/multipart/status":{"get":{"summary":"Read native Turbo multipart upload status","responses":{"200":{"description":"Multipart upload status"}}}},"/api/tus":{"options":{"summary":"Read TUS protocol capabilities","responses":{"204":{"description":"TUS capabilities"}}},"post":{"summary":"Create a TUS upload mapped to Ultra multipart","responses":{"201":{"description":"TUS upload created"}}}},"/api/tus/{uploadId}":{"head":{"summary":"Read TUS upload offset","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TUS upload offset"},"404":{"description":"Upload not found"}}},"patch":{"summary":"Append bytes to a TUS upload","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Bytes accepted"},"409":{"description":"Upload-Offset mismatch"}}},"delete":{"summary":"Terminate a TUS upload","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"TUS upload terminated"}}}},"/mcp":{"post":{"summary":"Hosted MCP Streamable HTTP JSON-RPC endpoint","description":"Supports initialize, notifications/initialized, ping, tools/list, and tools/call for hosted Ultra MCP tools: upload_text, resolve_share, request_grant, and download_link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"403":{"description":"Forbidden origin"}}},"get":{"summary":"Standalone MCP server events stream","description":"Not enabled for Ultra hosted MCP; clients should use Streamable HTTP POST request/response.","responses":{"405":{"description":"Use POST for Streamable HTTP JSON-RPC"}}}},"/api/folder/{folderId}/zip":{"get":{"summary":"Download ready folder files as a ZIP archive","parameters":[{"name":"folderId","in":"path","required":true,"schema":{"type":"string"}},{"name":"share_id","in":"query","required":false,"schema":{"type":"string"},"description":"Open folder share id for maxUses accounting."}],"responses":{"200":{"description":"ZIP stream"},"403":{"description":"Caller is not allowed to download from this folder"},"404":{"description":"Folder not found or no ready files"}}}},"/api/share/{shareId}":{"get":{"summary":"Resolve share metadata and policy","parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Share resolved"}}}},"/api/agent/auth":{"post":{"summary":"Exchange agent key for short-lived access token","responses":{"200":{"description":"Agent access token issued"}}}},"/api/agent/grants":{"post":{"summary":"Issue one-time access grant for an agent-gated share","responses":{"201":{"description":"Grant issued"}}}},"/api/dl/{id}":{"get":{"summary":"Download transfer bytes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"share_id","in":"query","required":false,"schema":{"type":"string"},"description":"Open share id for maxUses accounting."},{"name":"X-Access-Grant","in":"header","required":false,"schema":{"type":"string"},"description":"One-time agent grant for agent-gated targets."}],"responses":{"200":{"description":"Transfer stream"}}},"head":{"summary":"Read transfer headers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transfer headers"}}},"delete":{"summary":"Delete transfer before expiry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Delete-Token","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transfer deleted"},"401":{"description":"delete_token_required"},"403":{"description":"invalid_delete_token"}}}}},"components":{"schemas":{"UploadResponse":{"type":"object","required":["id","shareId","shareUrl","downloadUrl","expiresAt","deleteToken"],"properties":{"id":{"type":"string"},"shareId":{"type":"string"},"shareUrl":{"type":"string","format":"uri"},"downloadUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"deleteToken":{"type":"string"}}}}}}