# Accordio API documentation The Accordio developer reference: a public read-only JSON API, an OpenAPI 3.1 description, markdown versions of every page, and the scope metadata that says what an agent can do here without a credential. ## Overview Accordio publishes a small, read-only HTTP API describing the product itself: pricing, features, FAQ answers, integrations, and the catalogue of prebuilt AI agents. It exists so an agent can answer a question about Accordio from data rather than from scraped markup. Everything under https://accordio.ai/api is public. No key, no signup, no credential. Responses are JSON, including errors, and carry permissive CORS headers so a browser-based agent can call them directly. The API surface is versioned as 1.0.0. The version is reported in the /api index and bumped when a published response shape changes. ## Quickstart Start at the index. It lists every endpoint, every scope, and a link to each machine-readable document, so one request is enough to discover the rest. **Discover the API** ```bash curl -s https://accordio.ai/api | jq ``` ## Endpoints Every path below is relative to https://accordio.ai and answers GET without a credential. The authoritative list, with full schemas, is the OpenAPI document. - `GET /api` — Index of the public API (scope: public:read) - `GET /openapi.json` — This document (scope: public:read) - `GET /.well-known/oauth-protected-resource` — RFC 9728 protected-resource metadata (scope: public:read) - `GET /.well-known/oauth-authorization-server` — RFC 8414 authorization-server metadata (not published) (scope: public:read) - `GET /api/markdown` — Any page on accordio.ai, rendered as markdown (scope: public:read) - `GET /api/pricing` — Plan, trial, and credit tiers (scope: public:read) - `GET /api/features` — Product features (scope: public:read) - `GET /api/faq` — Frequently asked questions (scope: public:read) - `GET /api/integrations` — Apps Accordio connects to (scope: public:read) - `GET /api/agents` — Prebuilt AI agents (scope: public:read) ## Authentication and OAuth 2.0 The public API takes no credential. Every scope in the protected-resource metadata is granted to anonymous callers, subject to per-IP rate limits, and no token is issued or accepted for them. Accordio uses OAuth 2.0 in one direction only: as a client. When you connect Gmail, Google Calendar, Slack, Notion, or any other integration inside the product, Accordio runs the OAuth 2.0 authorization code flow against that provider and stores a scoped, revocable token. Accordio never sees the third-party password. Accordio does not yet run an OAuth 2.0 authorization server of its own, so there is no /.well-known/oauth-authorization-server document and no way for a third-party client to obtain an Accordio access token. That path returns a 404 with a JSON body saying exactly this, rather than metadata for a server that does not exist. What does exist is RFC 9728 protected resource metadata. Read it to learn which scopes this origin recognises, which are publicly grantable today, and where to ask about the rest. - [Protected resource metadata (RFC 9728)](https://accordio.ai/.well-known/oauth-protected-resource) — Published. Lists scopes_supported and the resource documentation URL. - [Authorization server metadata (RFC 8414)](https://accordio.ai/.well-known/oauth-authorization-server) — Not published. Accordio runs no public authorization server; the path returns a JSON 404 explaining where to go instead. - [Workspace API access](mailto:hello@accordio.ai) — Reading or writing contracts, invoices, clients, or time in a workspace is not publicly available. Email us if you need it. ## Scopes Scopes are published so an agent can reason about permission before it spends a round trip. The public scopes are what an anonymous caller gets. The restricted scopes are what Accordio's own clients use internally; they are listed for completeness and are not grantable to third parties today. ### Publicly grantable - `public:read` — Read public marketing and catalogue data: product features, pricing, FAQ, integrations, AI agents. - `scheduler:read` — Read a published Accordio booking page: host profile, event types, and free slots. - `scheduler:write` — Book or cancel a meeting on a published Accordio booking page. Mutating, rate limited, no credential required. ### Not publicly grantable - `contracts:read` — Read contracts and proposals in a workspace. - `contracts:write` — Create, edit, and send contracts and proposals. - `invoices:read` — Read invoices, payments, and reconciliation state. - `invoices:write` — Create and send invoices, and record payments. - `clients:read` — Read clients, leads, and projects. - `clients:write` — Create and update clients, leads, and projects. - `time:read` — Read tracked time entries and timesheets. - `time:write` — Start, stop, and edit time entries. ## Markdown instead of HTML Every page on https://accordio.ai has a markdown representation. Send `Accept: text/markdown` and you get the page as markdown instead of a JavaScript-heavy HTML document. Responses carry `Vary: Accept` so a cache never hands the wrong variant to the wrong client. Quality values are honoured. `Accept: text/markdown;q=0.9, text/html` still returns HTML, because HTML was rated higher. A client that accepts neither HTML nor markdown gets a 406 listing what this origin can produce. The same document is addressable directly, without content negotiation, if you would rather be explicit. **Two ways to get the same markdown** ```bash curl -s -H 'Accept: text/markdown' https://accordio.ai/pricing curl -s 'https://accordio.ai/api/markdown?path=/pricing' ``` ## Errors Errors under /api are JSON with a stable shape: a machine-readable `code`, a human `message`, a `hint` that says what to do next, the HTTP `status`, and a `documentation_url`. An unknown /api path returns that envelope rather than an HTML error page, and a 405 always carries the `Allow` header. Unknown paths elsewhere on the site return a real 404. Ask for markdown and the 404 body is markdown that links the sitemap, llms.txt, and this page. **A JSON 404** ```bash curl -s https://accordio.ai/api/not-a-real-endpoint | jq .error ``` ## Rate limits and caching Catalogue responses are cached for an hour at the edge and say so in `Cache-Control`. Error responses are never cached. There is no published per-key quota because there are no keys; abusive traffic is throttled per IP at the edge. Please cache what you fetch and send a descriptive User-Agent so we can tell agents apart from scrapers. ## Support The OpenAPI document is the contract. If something in it is wrong, or you need an endpoint that does not exist yet, email hello@accordio.ai. For how the product works rather than how to call it, read the product documentation at https://app.accordio.ai/docs or the Accordio app at https://app.accordio.ai. ## Every machine-readable document - [OpenAPI 3.1 description](https://accordio.ai/openapi.json) — Every publicly callable endpoint, request and response schema included. Also served as YAML at /api/openapi.yaml. - [API index](https://accordio.ai/api) — Endpoint list, scope list, and links to every other document, as JSON. - [Protected resource metadata](https://accordio.ai/.well-known/oauth-protected-resource) — RFC 9728. Names this origin as a protected resource and lists the scopes an anonymous caller actually gets. - [API catalog](https://accordio.ai/.well-known/api-catalog) — RFC 9727 linkset pointing at every API description document above. - [llms.txt](https://accordio.ai/llms.txt) — Plain-text map of the whole site: pages, features, agents, integrations, docs. - [Sitemap](https://accordio.ai/sitemap.xml) — Every indexable page, as XML. - [Product documentation](https://app.accordio.ai/docs) — How the product itself works: contracts, invoices, payments, time tracking, the AI assistant. --- Canonical HTML: https://accordio.ai/developers Site map for agents: https://accordio.ai/llms.txt API description: https://accordio.ai/openapi.json