{"version":1,"kind":"page","url":"https://www.onticord.ai/developers","title":"Build with Onticord","description":"Public API documentation, MCP quickstart, OAuth permissions, and a safe first request.","content":[{"type":"paragraph","content":["Connect your agent to Onticord, discover the tools available to a business, and request only the permissions your task needs."]},{"type":"paragraph","content":[{"type":"link","href":"https://www.onticord.ai/openapi.json","children":["OpenAPI 3.1 specification"]}," · ",{"type":"link","href":"https://auth.onticord.ai/llms.txt","children":["Agent connection guide"]}," · ",{"type":"link","href":"https://auth.onticord.ai/agents","children":["Connect an agent"]}]},{"type":"heading","level":2,"text":"Quickstart: no account or API key required"},{"type":"paragraph","content":["The website documents and public onboarding guide are free to read without an account, API key, or sales conversation. Start with these read-only requests:"]},{"type":"code","language":"sh","text":"curl --fail 'https://www.onticord.ai/openapi.json'\ncurl --fail 'https://www.onticord.ai/developers.json'\ncurl --fail 'https://auth.onticord.ai/llms.txt'"},{"type":"paragraph","content":["The OpenAPI document describes public HTTP reads and MCP tool discovery. Every operation has a unique operationId, description, and response schema. Public GET operations can be imported by HTTP function-calling clients; business tools use MCP and their live JSON Schemas."]},{"type":"heading","level":2,"text":"MCP endpoints and tool schemas"},{"type":"paragraph","content":["Public onboarding MCP: ",{"type":"link","href":"https://auth.onticord.ai/mcp","children":["https://auth.onticord.ai/mcp"]},". This service provides setup guidance and exposes account-creation tools; it does not grant business access."]},{"type":"paragraph","content":["Workspace MCP: ",{"type":"link","href":"https://api.onticord.ai/api/mcp","children":["https://api.onticord.ai/api/mcp"]},". Use an MCP client with Streamable HTTP and OAuth support. Tool names, descriptions, inputSchema, and available outputSchema are returned by tools/list. Follow nextCursor when present."]},{"type":"paragraph","content":["For a safe public discovery request, initialize the supported legacy protocol and then list the onboarding tools. Accept both JSON and SSE; parse the JSON-RPC data inside SSE frames. This stateless endpoint needs no session ID:"]},{"type":"code","language":"sh","text":"curl --fail 'https://auth.onticord.ai/mcp' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"onticord-quickstart\",\"version\":\"1.0.0\"}}}'\n\ncurl --fail 'https://auth.onticord.ai/mcp' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -H 'MCP-Protocol-Version: 2025-06-18' \\\n  --data '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}'\n\ncurl --fail 'https://auth.onticord.ai/mcp' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -H 'MCP-Protocol-Version: 2025-06-18' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'"},{"type":"heading","level":2,"text":"Authentication and least-privilege access"},{"type":"paragraph","content":["Onticord uses OAuth access tokens for workspace MCP, rather than personal API keys. The human signs in, selects a business, and approves the exact delegated permissions."]},{"type":"paragraph","content":[{"type":"link","href":"https://api.onticord.ai/.well-known/oauth-protected-resource","children":["Protected-resource metadata (RFC 9728)"]}," declares scopes_supported and the authorization server. ",{"type":"link","href":"https://auth.onticord.ai/.well-known/oauth-authorization-server/api/auth","children":["Authorization-server metadata"]}," declares authorization, token, and client-registration endpoints."]},{"type":"list","ordered":true,"items":[["Use the authorization-code flow with PKCE S256. Register your client through the published registration endpoint when your MCP client requires it."],["Send resource=https://api.onticord.ai in authorization and token requests. Use your registered redirect URI and validate state. Never put client secrets or bearer tokens in public URLs."],["Start with app.access for business reads and agent-connection verification. Request an additional scope only for the operation the human authorized. OAuth scopes constrain access; current business membership and human approval rules still apply."],["Send Authorization: Bearer <access_token> only to the workspace MCP endpoint. Use your MCP client's secure credential storage and refresh flow; a cookie or account alone is not workspace authorization."]]},{"type":"paragraph","content":["openid — Identify your account"]},{"type":"paragraph","content":["profile — View your name and profile"]},{"type":"paragraph","content":["email — View your email address"]},{"type":"paragraph","content":["offline_access — Keep access when you are away"]},{"type":"paragraph","content":["app.access — Read workflows and business data; create, restart and verify the agent connection test for this business"]},{"type":"paragraph","content":["agent.sessions — Create and use your private Player 2 conversations in this business"]},{"type":"paragraph","content":["business.name — Change only this business's display name"]},{"type":"paragraph","content":["workflows.run — Start paid or live workflows in this business"]},{"type":"paragraph","content":["workflows.simulate — Simulate workflows using connected reads"]},{"type":"paragraph","content":["skills.draft — Prepare skill drafts for human installation"]},{"type":"paragraph","content":["connections.manage — Connect, reconnect, or disconnect business services"]},{"type":"paragraph","content":["connections.gorgias.request — Prepare Gorgias setup or workload detach for business owner review"]},{"type":"paragraph","content":["connections.mailbox.request — Prepare Gmail inbox setup, reconnect, or detach for human review and consent"]},{"type":"paragraph","content":["members.read — View members and invitation delivery status"]},{"type":"paragraph","content":["members.request — Prepare access changes for human confirmation"]},{"type":"paragraph","content":["triggers.read — View event triggers and eligible configurations"]},{"type":"paragraph","content":["triggers.manage — Disable triggers or prepare trigger creation for human confirmation"]},{"type":"paragraph","content":["packs.manage — Enable, configure, upgrade, or disable vertical packs"]},{"type":"paragraph","content":["effects.request — Prepare unknown external write reconciliation for human confirmation"]},{"type":"paragraph","content":["gates.redeliver — Retry delivery of an existing human decision"]},{"type":"paragraph","content":["notifications.manage — Change your own approval notification settings, link your matching Slack account, and send yourself a test"]},{"type":"paragraph","content":["billing.read — View your business’s subscription, usage, and invoices"]},{"type":"paragraph","content":["billing.manage — Change your business’s subscription and payment details"]},{"type":"heading","level":2,"text":"Self-serve signup and first business request"},{"type":"paragraph","content":["Start at ",{"type":"link","href":"https://auth.onticord.ai/sign-up","children":["self-serve signup"]}," or ",{"type":"link","href":"https://auth.onticord.ai/agents","children":["agent connection setup"]},". Follow the current connection guide for the sign-in methods enabled in your environment. An agent must not send sign-in email or create an account without the account holder's authorization."]},{"type":"list","ordered":true,"items":[["After OAuth, discover workspace tools and call get_agent_connection_setup. Follow its nextAction and verify the exact setup attempt with verify_agent_connection."],["For a first commerce brief, use the current guide's read-only Commerce Intelligence flow. Check connected services and evidence coverage before claiming a result."],["Do not start a paid workflow merely to test connectivity. Money, access changes, Skill installation, and required runtime approvals remain human decisions."]]},{"type":"heading","level":2,"text":"Testing, sandbox, and pricing boundaries"},{"type":"paragraph","content":["Use the public GET requests and onboarding tool discovery above to test your client's HTTP, JSON, and MCP parsing without credentials or customer data. This is public discovery, not a simulated merchant sandbox."]},{"type":"paragraph","content":["A public hosted merchant sandbox, self-serve API-key issuance, and a general free usage tier are not currently offered here. Shopify installation is free; metered usage requires a separately approved Shopify plan. Signing in does not enable charges. Confirm the available plan and permissions in the hosted onboarding flow before live work."]},{"type":"heading","level":2,"text":"Errors and limits"},{"type":"list","ordered":false,"items":[["401 from workspace MCP means missing or invalid authorization. Read WWW-Authenticate and follow protected-resource discovery; do not retry the same invalid token indefinitely."],["403 means the request is not permitted. Check the origin, business membership, and required scopes instead of requesting broader access automatically."],["429 means rate limited. Honor Retry-After when supplied, otherwise use bounded exponential backoff with jitter. No universal requests-per-minute quota is promised by this documentation."],["An HTTP 200 can still carry a JSON-RPC error or a tool result with isError. Inspect the protocol envelope and tool result. Do not blindly retry writes after a timeout."],["GET on the public onboarding /mcp endpoint returns 405: it requires POST. Public onboarding request bodies are limited to 16 KiB. Browser access is restricted to trusted origins; use a supported MCP client for OAuth."]]},{"type":"paragraph","content":[{"type":"link","href":"https://www.onticord.ai/contact","children":["Support"]}," · ",{"type":"link","href":"https://www.onticord.ai/privacy","children":["Privacy"]}," · ",{"type":"link","href":"https://www.onticord.ai/terms","children":["Terms"]}]}],"links":{"html":"https://www.onticord.ai/developers","markdown":"https://www.onticord.ai/developers.md","json":"https://www.onticord.ai/developers.json","agentInstructions":"https://auth.onticord.ai/llms.txt"}}