{"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.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":"Optional open-link byte fetch limit. Omit for TTL-only access."},"auth_mode":{"type":"string","enum":["open","agent"]},"allowed_agent_ids":{"type":"string"},"policy_template_id":{"type":"string","enum":["public","public-once","agent-only","expiring-handoff","passcode-ready"],"description":"Optional built-in policy template. Explicit policy fields remain overrides."},"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"}},"policyTemplateId":{"type":"string","enum":["public","public-once","agent-only","expiring-handoff","passcode-ready"],"description":"Optional built-in policy template. Explicit policy fields remain overrides."},"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"}},"policyTemplateId":{"type":"string","enum":["public","public-once","agent-only","expiring-handoff","passcode-ready"],"description":"Optional built-in policy template. Explicit policy fields remain overrides."},"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, upload_json, 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. File shares include canonical mimeType metadata; contentType is HTTP/R2 transport vocabulary, not a JSON response alias.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareResolveResponse"}}}}}}},"/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/agent/groups":{"post":{"summary":"Create an owner-scoped agent group","description":"Session-authenticated control-plane endpoint. Group policy defaults are authoring conveniences and do not widen existing shares.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"members":{"type":"array","maxItems":100,"items":{"oneOf":[{"type":"string"},{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"},"role":{"type":"string","enum":["member","manager"]}}}]}},"policyDefaults":{"$ref":"#/components/schemas/AgentGroupPolicyDefaults"}}}}}},"responses":{"201":{"description":"Agent group created","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"$ref":"#/components/schemas/AgentGroupRecord"}}}}}}}},"get":{"summary":"List owner-scoped agent groups","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Agent group page","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"groups":{"type":"array","items":{"$ref":"#/components/schemas/AgentGroupRecord"}}}}}}}}}},"/api/agent/groups/{groupId}":{"patch":{"summary":"Update an owner-scoped agent group","description":"Updates name and policyDefaults only. Membership changes are reserved for dedicated membership endpoints.","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"policyDefaults":{"$ref":"#/components/schemas/AgentGroupPolicyDefaults"}}}}}},"responses":{"200":{"description":"Agent group updated"},"400":{"description":"Invalid group update"},"404":{"description":"Agent group not found"}}},"delete":{"summary":"Delete an owner-scoped agent group","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent group deleted"},"404":{"description":"Agent group not found"}}}},"/api/agent/groups/{groupId}/members":{"post":{"summary":"Add an agent to an owner-scoped group","description":"Adds one member without automatically widening policyDefaults.allowedAgentIds.","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"},"role":{"type":"string","enum":["member","manager"]}}}}}},"responses":{"201":{"description":"Agent group member added"},"404":{"description":"Agent group not found"},"409":{"description":"Agent is already a member or group is full"}}}},"/api/agent/groups/{groupId}/members/{agentId}":{"delete":{"summary":"Remove an agent from an owner-scoped group","description":"Removes one member and prunes that agent from policyDefaults.allowedAgentIds when present.","parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string"}},{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent group member removed"},"404":{"description":"Agent group or member not found"}}}},"/api/agent/permissions":{"post":{"summary":"Create an owner-scoped standing permission","description":"Creates an agent-to-agent standing permission record for future resolve/grant-time enforcement. Runtime enforcement is deferred until permission use/denial audit paths land.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromAgentId","toAgentId"],"properties":{"fromAgentId":{"type":"string"},"toAgentId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["share.resolve","grant.issue"]}},"constraints":{"$ref":"#/components/schemas/StandingPermissionConstraints"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Standing permission created","content":{"application/json":{"schema":{"type":"object","properties":{"permission":{"$ref":"#/components/schemas/StandingPermissionRecord"}}}}}}}},"get":{"summary":"List owner-scoped standing permissions","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Standing permission page","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/StandingPermissionRecord"}}}}}}}}}},"/api/agent/permissions/{permissionId}":{"delete":{"summary":"Revoke an owner-scoped standing permission","parameters":[{"name":"permissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Standing permission revoked"},"404":{"description":"Standing permission not found"}}}},"/api/audit":{"get":{"summary":"Query audit events","description":"Authenticated owner-session endpoint for paginated audit event history. Supports indexed filters for event type, agent id, target id/type, share id, and occurred-at time range.","parameters":[{"name":"eventType","in":"query","required":false,"schema":{"type":"string"}},{"name":"agentId","in":"query","required":false,"schema":{"type":"string"}},{"name":"targetType","in":"query","required":false,"schema":{"type":"string","enum":["file","pipe","folder","share","grant","agent_key","policy","agent_group","standing_permission"]}},{"name":"targetId","in":"query","required":false,"schema":{"type":"string"}},{"name":"shareId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audit event page"},"401":{"description":"Authentication required"}}}},"/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"}}},"ShareResolveResponse":{"type":"object","required":["id","type","targetId","policy","createdByUserId","createdByAgentId"],"properties":{"id":{"type":"string"},"shareId":{"type":"string","description":"Legacy compatibility alias for id."},"type":{"type":"string","enum":["file","pipe","folder"]},"targetId":{"type":"string"},"fileId":{"type":"string","description":"Present for file shares."},"pipeId":{"type":"string","description":"Present for pipe shares; also present as a legacy alias on file shares."},"folderId":{"type":"string","description":"Present for folder shares."},"filename":{"type":"string","description":"File name, present for file shares when target metadata exists."},"mimeType":{"type":"string","description":"Canonical JSON content-type signal for file target metadata."},"size":{"type":"integer","minimum":0,"description":"File size in bytes, present for file shares when target metadata exists."},"expiresAt":{"type":"string","format":"date-time","description":"Target file metadata expiry, present for file shares when target metadata exists."},"policy":{"type":"object","required":["mode","allowedAgentIds","expiresAt","metadata"],"properties":{"mode":{"type":"string","enum":["open","agent"]},"allowedAgentIds":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"},"maxUses":{"type":"integer","minimum":1},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"createdByUserId":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"]},"authMode":{"type":"string","enum":["open","agent"],"description":"Legacy compatibility alias for policy.mode."}}},"AgentGroupPolicyDefaults":{"type":"object","required":["mode","allowedAgentIds"],"properties":{"mode":{"type":"string","const":"agent"},"allowedAgentIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"maxTtlSeconds":{"type":"integer","minimum":1,"maximum":604800},"maxUses":{"type":"integer","minimum":1},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"AgentGroupRecord":{"type":"object","required":["id","ownerId","name","members","policyDefaults","createdAt","updatedAt","version"],"properties":{"id":{"type":"string","pattern":"^agrp_"},"ownerId":{"type":"string"},"name":{"type":"string"},"members":{"type":"array","items":{"type":"object","required":["agentId","role","addedAt"],"properties":{"agentId":{"type":"string"},"role":{"type":"string","enum":["member","manager"]},"addedAt":{"type":"string","format":"date-time"},"addedByAgentId":{"type":["string","null"]}}}},"policyDefaults":{"$ref":"#/components/schemas/AgentGroupPolicyDefaults"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByAgentId":{"type":["string","null"]},"version":{"type":"integer","minimum":1}}},"StandingPermissionConstraints":{"type":"object","required":["allowedPolicyModes"],"properties":{"allowedPolicyModes":{"type":"array","items":{"type":"string","enum":["agent"]}},"targetTypes":{"type":"array","items":{"type":"string","enum":["file","pipe","folder"]}},"contentTypes":{"type":"array","maxItems":25,"items":{"type":"string"}},"maxShareTtlSeconds":{"type":"integer","minimum":1,"maximum":604800},"maxGrantTtlSeconds":{"type":"integer","minimum":1,"maximum":300},"policyMetadata":{"type":"object","additionalProperties":{"type":"string"}}}},"StandingPermissionRecord":{"type":"object","required":["id","ownerId","from","to","scopes","constraints","createdAt","updatedAt","audit","version"],"properties":{"id":{"type":"string","pattern":"^perm_"},"ownerId":{"type":"string"},"from":{"type":"object","required":["type","agentId"],"properties":{"type":{"type":"string","const":"agent"},"agentId":{"type":"string"}}},"to":{"type":"object","required":["type","agentId"],"properties":{"type":{"type":"string","const":"agent"},"agentId":{"type":"string"}}},"scopes":{"type":"array","items":{"type":"string","enum":["share.resolve","grant.issue"]}},"constraints":{"$ref":"#/components/schemas/StandingPermissionConstraints"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","format":"date-time"},"audit":{"type":"object","additionalProperties":true},"version":{"type":"integer","minimum":1}}}}}}