{"openapi":"3.1.1","info":{"title":"Onticord public discovery API","version":"1.0.0","description":"Public website reads and read-only MCP discovery. Merchant operations use the OAuth-protected MCP service, not REST routes on the website. Scopes describe delegated permissions, not business membership or human approval. No API key is required for public discovery.","contact":{"name":"Onticord","url":"https://www.onticord.ai/contact"}},"servers":[{"url":"https://www.onticord.ai","description":"Public website; MCP operations override this server below."}],"externalDocs":{"description":"Developer quickstart, OAuth and testing","url":"https://www.onticord.ai/developers"},"security":[],"tags":[{"name":"Public reads"},{"name":"OAuth discovery"},{"name":"MCP discovery"}],"paths":{"/health":{"get":{"operationId":"getWebsiteHealth","summary":"Check website health","tags":["Public reads"],"description":"Check the public website process. This does not attest to merchant connections or workflow readiness.","responses":{"200":{"description":"Website is responding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/llms.txt":{"get":{"operationId":"getAgentInstructions","summary":"Read agent instructions","tags":["Public reads"],"description":"Read public product guidance and links to the current identity-service connection guide. Does not grant business access.","responses":{"200":{"description":"Plain-text agent guide.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/index.json":{"get":{"operationId":"getProductOverview","summary":"Read product overview","tags":["Public reads"],"description":"Read the versioned public page document with typed content blocks and canonical links. Examples are illustrative, not merchant evidence.","responses":{"200":{"description":"Version 1 public page representation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDocument"}}}}}}},"/developers.json":{"get":{"operationId":"getDeveloperDocumentation","summary":"Read developer documentation","tags":["Public reads"],"description":"Read the versioned public page document with typed content blocks and canonical links. Examples are illustrative, not merchant evidence.","responses":{"200":{"description":"Version 1 public page representation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDocument"}}}}}}},"/.well-known/oauth-protected-resource":{"servers":[{"url":"https://api.onticord.ai"}],"get":{"operationId":"getWorkspacePermissions","summary":"Discover workspace OAuth permissions","tags":["OAuth discovery"],"description":"RFC 9728 metadata served by the actual protected resource. Request only the scopes needed for the merchant's task.","responses":{"200":{"description":"Resource identifier, authorization servers and supported scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResource"}}}}}}},"/mcp":{"servers":[{"url":"https://auth.onticord.ai"}],"post":{"operationId":"listOnboardingTools","summary":"Discover public onboarding tools","description":"Read-only MCP tools/list request. Use an MCP client to initialize and negotiate the protocol first. This OpenAPI operation describes tool discovery only, not every MCP method. Tool inputSchema/outputSchema are discovered at runtime; execute tools through an MCP client. Accept must include application/json and text/event-stream. Responses may be JSON or an SSE stream of JSON-RPC messages.","tags":["MCP discovery"],"security":[],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":true,"description":"The version negotiated during MCP initialization. This example uses the supported legacy transport.","schema":{"type":"string"},"example":"2025-06-18"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListToolsRequest"},"example":{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}}}},"responses":{"200":{"description":"Tool discovery result or JSON-RPC error. For SSE, parse each data field as JSON-RPC.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ListToolsResponse"},{"$ref":"#/components/schemas/RpcError"}]}},"text/event-stream":{"schema":{"type":"string","description":"SSE frames carrying ListToolsResponse or RpcError JSON in data fields."}}}},"403":{"description":"Origin, host, membership, or delegated permission rejected."},"429":{"description":"Rate limited. Honor Retry-After when present; otherwise back off with jitter.","headers":{"Retry-After":{"description":"Delay in seconds or HTTP date, when supplied.","schema":{"type":"string"}}}},"default":{"description":"HTTP transport error; do not treat it as a successful tool result."}}}},"/api/mcp":{"servers":[{"url":"https://api.onticord.ai"}],"post":{"operationId":"listWorkspaceTools","summary":"Discover workspace tools","description":"Read-only MCP tools/list request. Use an MCP client to initialize and negotiate the protocol first. This OpenAPI operation describes tool discovery only, not every MCP method. Tool inputSchema/outputSchema are discovered at runtime; execute tools through an MCP client. Accept must include application/json and text/event-stream. Responses may be JSON or an SSE stream of JSON-RPC messages.","tags":["MCP discovery"],"security":[{"WorkspaceOAuth":["app.access"]}],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":true,"description":"The version negotiated during MCP initialization. This example uses the supported legacy transport.","schema":{"type":"string"},"example":"2025-06-18"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListToolsRequest"},"example":{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}}}},"responses":{"200":{"description":"Tool discovery result or JSON-RPC error. For SSE, parse each data field as JSON-RPC.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ListToolsResponse"},{"$ref":"#/components/schemas/RpcError"}]}},"text/event-stream":{"schema":{"type":"string","description":"SSE frames carrying ListToolsResponse or RpcError JSON in data fields."}}}},"401":{"description":"Bearer token missing or invalid. WWW-Authenticate identifies the protected-resource metadata.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer challenge with resource_metadata discovery URL."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"403":{"description":"Origin, host, membership, or delegated permission rejected."},"429":{"description":"Rate limited. Honor Retry-After when present; otherwise back off with jitter.","headers":{"Retry-After":{"description":"Delay in seconds or HTTP date, when supplied.","schema":{"type":"string"}}}},"default":{"description":"HTTP transport error; do not treat it as a successful tool result."}}}}},"components":{"securitySchemes":{"WorkspaceOAuth":{"type":"oauth2","description":"Authorization code with PKCE S256 and resource=https://api.onticord.ai. Human sign-in, business selection and consent are required. Discover registration and server capabilities at https://auth.onticord.ai/.well-known/oauth-authorization-server/api/auth.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.onticord.ai/api/auth/oauth2/authorize","tokenUrl":"https://auth.onticord.ai/api/auth/oauth2/token","refreshUrl":"https://auth.onticord.ai/api/auth/oauth2/token","scopes":{"openid":"Identify your account","profile":"View your name and profile","email":"View your email address","offline_access":"Keep access when you are away","app.access":"Read workflows and business data; create, restart and verify the agent connection test for this business","agent.sessions":"Create and use your private Player 2 conversations in this business","business.name":"Change only this business's display name","workflows.run":"Start paid or live workflows in this business","workflows.simulate":"Simulate workflows using connected reads","skills.draft":"Prepare skill drafts for human installation","connections.manage":"Connect, reconnect, or disconnect business services","connections.gorgias.request":"Prepare Gorgias setup or workload detach for business owner review","connections.mailbox.request":"Prepare Gmail inbox setup, reconnect, or detach for human review and consent","members.read":"View members and invitation delivery status","members.request":"Prepare access changes for human confirmation","triggers.read":"View event triggers and eligible configurations","triggers.manage":"Disable triggers or prepare trigger creation for human confirmation","packs.manage":"Enable, configure, upgrade, or disable vertical packs","effects.request":"Prepare unknown external write reconciliation for human confirmation","gates.redeliver":"Retry delivery of an existing human decision","notifications.manage":"Change your own approval notification settings, link your matching Slack account, and send yourself a test","billing.read":"View your business’s subscription, usage, and invoices","billing.manage":"Change your business’s subscription and payment details"}}}}},"schemas":{"Health":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"service":{"type":"string","const":"www"}},"required":["ok","service"]},"ProtectedResource":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}}},"required":["resource","authorization_servers","scopes_supported"]},"OAuthError":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error"]},"Inline":{"oneOf":[{"type":"string"},{"type":"object","properties":{"type":{"const":"link"},"href":{"type":"string","format":"uri"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Inline"}}},"required":["type","href","children"]},{"type":"object","properties":{"type":{"const":"strong"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Inline"}}},"required":["type","children"]}]},"Block":{"oneOf":[{"type":"object","properties":{"type":{"const":"heading"},"level":{"type":"integer","enum":[2,3]},"text":{"type":"string"},"id":{"type":"string"}},"required":["type","level","text"]},{"type":"object","properties":{"type":{"enum":["paragraph","quote"]},"content":{"type":"array","items":{"$ref":"#/components/schemas/Inline"}}},"required":["type","content"]},{"type":"object","properties":{"type":{"const":"list"},"ordered":{"type":"boolean"},"items":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/Inline"}}}},"required":["type","ordered","items"]},{"type":"object","properties":{"type":{"const":"example"},"title":{"type":"string"},"content":{"type":"array","items":{"$ref":"#/components/schemas/Block"}}},"required":["type","title","content"]},{"type":"object","properties":{"type":{"const":"code"},"language":{"type":"string"},"text":{"type":"string"}},"required":["type","language","text"]}]},"PageDocument":{"type":"object","properties":{"version":{"type":"integer","const":1},"kind":{"type":"string","const":"page"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"array","items":{"$ref":"#/components/schemas/Block"}},"links":{"type":"object","properties":{"html":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"},"json":{"type":"string","format":"uri"},"agentInstructions":{"type":"string","format":"uri"}},"required":["html","markdown","json","agentInstructions"]}},"required":["version","kind","url","title","description","content","links"]},"ListToolsRequest":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer"]},"method":{"type":"string","const":"tools/list"},"params":{"type":"object","properties":{"cursor":{"type":"string"}},"required":[]}},"required":["jsonrpc","id","method"]},"ListToolsResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer"]},"result":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"nextCursor":{"type":"string"}},"required":["tools"]}},"required":["jsonrpc","id","result"]},"Tool":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","description":"JSON Schema describing this tool's arguments.","additionalProperties":true},"outputSchema":{"type":"object","description":"Optional JSON Schema for structured results.","additionalProperties":true}},"required":["name","inputSchema"]},"RpcError":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer","null"]},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc","id","error"]}}},"x-onticord-agent-guide":"https://auth.onticord.ai/llms.txt"}