{"openapi":"3.1.0","info":{"title":"OwAI remote media-library MCP transport","version":"1.0.0","description":"Connect AI assistants to the authenticated account's OwAI photo and video library using MCP Streamable HTTP. Permanent paid Cloud Access is required. Hosted semantic searches use separate prepaid credits; metadata-only searches and library-management calls do not consume inference credits. This OpenAPI document describes HTTP transport and discovery only. Use MCP tools/list for the current tool names and their authoritative input/output schemas, then tools/call to invoke them. The server is stateless and does not issue Mcp-Session-Id. Legacy MCP requests use POST response streams; current per-request MCP exchanges may return JSON. Use an MCP client that supports the negotiated protocol revision. Local folders and Apple Photos must be indexed and synced. Remote local-source mutations need the owning app online; media previews also need Remote media access. Supported OneDrive operations use the connected cloud account."},"servers":[{"url":"https://index.organizewith.ai","description":"Production OwAI media index"}],"externalDocs":{"url":"https://organizewith.ai/en/guides/connect-ai-assistants","description":"Connect an assistant and authorize your account"},"security":[{"bearerAuth":[]}],"x-mcp-endpoint":"https://index.organizewith.ai/mcp","x-oauth-protected-resource-metadata":"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp","x-oauth-scopes":{"media:search":"Search the synced media library.","media:read":"Locate media, list devices and sources, and read supported media content.","library:read":"Inspect library organization and command results.","library:write":"Create and update supported library organization.","library:delete":"Run reviewed deletion operations; explicit approval is still required.","ACCESS_VIEW_MANAGE_MCP_CONTENT":"Gemini compatibility scope granting the five media/library scopes above.","SHARE_THROUGH_MCP_CONVERSATION_INFO":"Gemini conversation-sharing consent; grants no library permission by itself."},"paths":{"/mcp":{"description":"The public remote MCP endpoint. Authentication is checked before transport method validation.","post":{"operationId":"sendMcpMessage","summary":"Discover or call OwAI MCP tools","description":"Send a JSON-RPC 2.0 MCP message with Content-Type: application/json and Accept: application/json, text/event-stream. The examples use the supported 2025-11-25 compatibility protocol: initialize, send notifications/initialized, then tools/list and tools/call. Send MCP-Protocol-Version on subsequent requests. For the current per-request protocol, let an MCP SDK supply the required request metadata and MCP headers. The server uses JSON responses for ordinary current-protocol calls; legacy calls return SSE message events containing JSON-RPC responses. Tool errors can appear in a successful HTTP response as a JSON-RPC error or a tool result with isError: true. Inspect the result before reporting success. Pending library commands require get_library_command to verify completion.","parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"Negotiated MCP revision. Subsequent compatibility requests should send the revision returned by initialize; current-protocol clients must also provide their required per-request metadata.","schema":{"type":"string"},"example":"2025-11-25"},{"name":"Mcp-Method","in":"header","required":false,"description":"Current-protocol MCP method header; supplied by the MCP SDK and matched to the JSON-RPC method.","schema":{"type":"string"}},{"name":"Mcp-Name","in":"header","required":false,"description":"Current-protocol target name header where required by the MCP method; supplied by the MCP SDK.","schema":{"type":"string"}},{"name":"device_id","in":"query","required":false,"description":"Optional local-opening binding from the device-specific URL shown in OwAI Settings. Omit for general remote access; never invent a device ID.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcMessage"},"examples":{"initialize":{"summary":"Initialize the compatibility protocol","value":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"owai-api-client","version":"1.0.0"}}}},"initialized":{"value":{"jsonrpc":"2.0","method":"notifications/initialized"}},"listTools":{"value":{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}},"callTool":{"summary":"Read-only device listing, requiring media:read","value":{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_media_devices","arguments":{}}}}}}}},"responses":{"200":{"description":"JSON-RPC result/error, or an SSE stream of JSON-RPC message events. Tool content may include text, inline images, resource links, structuredContent and isError; consult the live tool schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"},"example":"event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":3,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"No devices have synced a media index yet.\"}],\"structuredContent\":{\"devices\":[]}}}\n\n"}}},"202":{"description":"Notification accepted; the response has no body."},"400":{"description":"Malformed JSON, invalid JSON-RPC message, or invalid protocol metadata/version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Missing or invalid credentials. Follow the resource_metadata URL in WWW-Authenticate to discover OAuth authorization.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"403":{"description":"Host or Origin is not allowed. Tool-level permission failures are returned through MCP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"406":{"description":"Compatibility requests must accept both application/json and text/event-stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"default":{"description":"Protocol, service or upstream failure. JSON-RPC errors and HTTP-level errors use different envelopes.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcError"},{"$ref":"#/components/schemas/HttpError"}]}}}}}},"get":{"operationId":"unsupportedMcpGet","summary":"Standalone GET streams are unsupported","responses":{"401":{"description":"Missing or invalid credentials. Follow the resource_metadata URL in WWW-Authenticate to discover OAuth authorization.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"403":{"description":"Host or Origin is not allowed. Tool-level permission failures are returned through MCP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"405":{"description":"The stateless endpoint does not provide a standalone GET event stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}},"delete":{"operationId":"unsupportedMcpDelete","summary":"Session deletion is unsupported","responses":{"401":{"description":"Missing or invalid credentials. Follow the resource_metadata URL in WWW-Authenticate to discover OAuth authorization.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"403":{"description":"Host or Origin is not allowed. Tool-level permission failures are returned through MCP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"405":{"description":"The stateless endpoint does not create sessions to delete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}}},"/assets/{assetId}/content":{"description":"Authenticated media delivery through the existing local-folder, Apple Photos or OneDrive source. Never place credentials in the URL. A media:read grant is required.","parameters":[{"name":"assetId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"variant","in":"query","schema":{"type":"string","enum":["preview","original","image","stream"],"default":"preview"},"description":"Use stream for full video delivery and byte-range seeking; image adapts an image to the inline budget."},{"name":"Range","in":"header","schema":{"type":"string"},"description":"One byte range, such as bytes=0-1048575, bytes=1048576-, or bytes=-65536. Multipart ranges are unsupported."},{"name":"If-Range","in":"header","schema":{"type":"string"},"description":"For stream, only a matching strong ETag preserves the requested range. Otherwise the full representation is returned."}],"get":{"operationId":"readMediaContent","summary":"Read authenticated image bytes or stream a video","description":"Video stream links come from read_media. Large videos stream in bounded upstream ranges without buffering the whole movie. OneDrive needs no desktop; local files and Apple Photos require the owning app and opt-in relay. Photos may first download/export the current video on its Mac. The client must support authenticated fetching and the source codec. A start_ms playback hint appears in the URL fragment, not a server-side clip parameter.","responses":{"200":{"description":"Complete media body. A provider that ignores Range also returns 200, with Accept-Ranges: none.","content":{"video/mp4":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Requested video byte range, with Content-Range and Content-Length."},"401":{"description":"Missing or invalid credentials. Follow the resource_metadata URL in WWW-Authenticate to discover OAuth authorization.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"403":{"description":"Host or Origin is not allowed. Tool-level permission failures are returned through MCP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Asset or source file unavailable in this account."},"416":{"description":"Invalid, multipart or unsatisfiable range."},"502":{"description":"Source response is inconsistent or incomplete. A mid-stream failure aborts the body."},"503":{"description":"Owning device offline, remote media access disabled or provider unavailable."},"504":{"description":"Source preparation timed out; an iCloud export may still be preparing on the Mac."}}},"head":{"operationId":"inspectVideoContent","summary":"Inspect video size and range support without downloading the movie","description":"Use variant=stream. Probes one source byte; an uncached Apple Photos video still needs native preparation first.","responses":{"200":{"description":"Video content headers, no response body."},"206":{"description":"Requested range headers, no body."},"401":{"description":"Missing or invalid credentials. Follow the resource_metadata URL in WWW-Authenticate to discover OAuth authorization.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"403":{"description":"Host or Origin is not allowed. Tool-level permission failures are returned through MCP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Media not found."},"416":{"description":"Invalid range."},"503":{"description":"Source unavailable."}}}},"/health":{"get":{"operationId":"getMediaIndexHealth","summary":"Check public service liveness","description":"Confirms the HTTP service responded; does not verify account authorization, library sync, media availability or indexing completion.","security":[],"responses":{"200":{"description":"The HTTP service is responding.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}},"example":{"ok":true}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"getMcpOAuthResourceMetadata","summary":"Discover OAuth authorization for remote MCP","security":[],"responses":{"200":{"description":"RFC 9728 protected-resource metadata. Fetch the authorization server's metadata to discover its current OAuth endpoints and supported scopes.","content":{"application/json":{"schema":{"type":"object","required":["resource","authorization_servers","scopes_supported","bearer_methods_supported","resource_name"],"properties":{"resource":{"type":"string","format":"uri","example":"https://index.organizewith.ai/mcp"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"},"example":["https://index.organizewith.ai"]},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"},"example":["header"]},"resource_name":{"type":"string","example":"OwAI media library"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Obtain an OAuth access token through the authorization server discovered at https://index.organizewith.ai/.well-known/oauth-protected-resource/mcp. Send Authorization: Bearer <access-token>. Granted scopes are checked per tool; request only the permissions needed. Tokens and account-specific IDs must never be included in public URLs. Legacy developer keys are not needed for normal assistant setup."}},"schemas":{"JsonRpcMessage":{"type":"object","required":["jsonrpc","method"],"description":"A single MCP JSON-RPC request or notification. Include id for a request and omit it for a notification. Method-specific params and current-protocol metadata follow the negotiated MCP revision.","properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}},"JsonRpcResponse":{"oneOf":[{"type":"object","required":["jsonrpc","id","result"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"result":{"type":"object","additionalProperties":true}}},{"$ref":"#/components/schemas/JsonRpcError"}]},"JsonRpcError":{"type":"object","required":["jsonrpc","id","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}},"HttpError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}