--- title: "API reference" description: "The planned Matchai API: base URL, authentication, pagination, idempotency, request ids and how to read the Coming soon badges. Download the OpenAPI file." last_updated: "2026-10-21" lang: "en" status: "coming-soon" canonical: "https://matchai.co/docs/developers/api-reference" --- # API reference > The planned Matchai API: base URL, authentication, pagination, idempotency, request ids and how to read the Coming soon badges. Download the OpenAPI file. **Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.** Source: https://matchai.co/docs/developers/api-reference This is the reference for the Matchai API, which lets an app act for **one Matchai account**: listings, contacts, conversations, calendar, documents, sites, the Matchai Page and webhooks. It is generated from the API's OpenAPI contract. The API is coming soon. Every operation in this reference is marked **Coming soon**, and none of it works yet. The reference is published now so that partners and developers can plan, and details can still change before the API opens. ## The basics [#the-basics] | | | |---|---| | Base URL | `https://api.matchai.co/v1` | | Authentication | `Authorization: Bearer matchai_…` with an [API key](https://matchai.co/docs/developers/authentication/api-keys), or an access token from [Connect with Matchai](https://matchai.co/docs/developers/authentication/connect-with-matchai) | | Content type | JSON (`application/json; charset=utf-8`). File uploads use `multipart/form-data`. | | Field names | `snake_case` | | Ids | Opaque strings. Store and compare them. Never parse or build them. | | Timestamps | ISO 8601. Send a UTC offset, such as `2026-10-25T10:00:00-04:00`. Responses use UTC (`Z`), except appointment times, which keep the appointment's own offset. | | Dates | `YYYY-MM-DD` | | Money | `{ "amount": 649000, "currency": "CAD" }`, with the amount in the currency's main unit | | Languages | `en-US`, `fr-CA` (Québec French) and `es`. The `message` of an error follows the account's language. | Two conventions save surprises: - **Empty values.** Optional fields are always present in responses, as `null` or `[]` when empty. In a `PATCH` request, leave a field out to keep it and send `null` to clear it. - **Open enums.** New values, fields and event types can be added without a new version. Treat an unknown value as "other" and ignore unknown fields. See [versioning](https://matchai.co/docs/developers/versioning). ## Pagination [#pagination] List endpoints take `limit` (1 to 100, default 25) and `cursor`, and return one page: ```json title="Response" { "data": [], "next_cursor": "…" } ``` Pass `next_cursor` back as `cursor` to get the next page. When `next_cursor` is `null`, you have reached the end. A cursor expires after 24 hours, so use it right away. ```js title="paginate.mjs" async function* listAll(path, params = {}) { let cursor = null; do { const url = new URL(`https://api.matchai.co/v1${path}`); for (const [name, value] of Object.entries({ limit: 100, ...params })) { url.searchParams.set(name, value); } if (cursor) url.searchParams.set('cursor', cursor); const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}` }, }); if (!response.ok) throw new Error(`Matchai answered ${response.status}`); const page = await response.json(); yield* page.data; cursor = page.next_cursor; } while (cursor); } for await (const listing of listAll('/listings', { status: 'published' })) { console.log(listing.title); } ``` ## Idempotency [#idempotency] Send an `Idempotency-Key` header on every `POST`. A UUID works. If a request times out, repeat it with the same key: a retry within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns `409 idempotency_key_reused`. See [retry safely](https://matchai.co/docs/developers/errors#retry-safely). ## Request ids [#request-ids] Every response carries a `Matchai-Request-Id` header, such as `req_7Hq2LmZ9xV4c`. Log it, and include it when you contact [Matchai support](https://matchai.co/support). ## Errors and rate limits [#errors-and-rate-limits] Every error has the same JSON shape, `{ "error": { "type", "code", "message", "param", "doc_url", "request_id" } }`. Branch on `code`, and show `message` to people. The statuses are `400` invalid request, `401` missing or expired credentials, `402` not enough Energy, `403` missing scope or role, `404` not found, `409` conflict, `422` refused by a product rule, `429` rate limited and `500` an error on Matchai's side. Every code is on the [errors](https://matchai.co/docs/developers/errors) page. Limits apply per connection. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and a `429` adds `Retry-After`. See [rate limits](https://matchai.co/docs/developers/rate-limits#in-the-matchai-api). ## Final actions [#final-actions] Operations that send something to another person, publish something to the public, pay, or delete the account's content are **final actions**. Depending on the setting the account holder chose for your app, they either run straight away (**Allowed**) or return `202 Accepted` with an `approval_url` and wait (**Ask me**, the default). Write your app for both. See [final actions](https://matchai.co/docs/developers/authentication#final-actions). ## How to read an operation [#how-to-read-an-operation] Each operation page starts with its summary, which begins "Coming soon", and then lists what the operation needs. These are the marks you will see, as they appear in the OpenAPI file: | Mark | Meaning | |---|---| | `x-matchai-status` | `coming-soon` today. It becomes `live` when the endpoint ships, and the Coming soon badge disappears from its page in the same release. | | **Scopes** | The [scopes](https://matchai.co/docs/developers/authentication#scopes) a key or token needs to call the operation. | | `x-matchai-pricing` | `free`: public information, no connection needed. `connection`: included with the account's connection to your app. `energy`: included with the connection, and the action also spends Matchai Energy. | | `x-matchai-approval` | `final-action`: the operation waits for approval under **Ask me**. | | `x-matchai-energy-tier` | How heavy an Energy-spending action is: `light`, `moderate`, `heavy` or `varies`. Energy is never a number in the API. | Connecting an app to an account is a paid Matchai Connector. An app that is connected only to its developer's own account is in free test mode. See [create a Matchai app](https://matchai.co/docs/developers/authentication/create-a-matchai-app#who-pays). ## Download the OpenAPI file [#download-the-openapi-file] The contract behind this reference is an OpenAPI 3.1 file: ```text title="OpenAPI file" https://matchai.co/docs/openapi/matchai-v1.yaml ``` You can load it into an API client, a mock server or a code generator. It is a preview, and every operation in it is marked `coming-soon`, so do not ship an integration against it yet. The OpenAPI file for the public, read-only surfaces that work today is at `https://matchai.co/openapi.json`. ## Resources [#resources] The account your credentials act for, and the connection itself. Public profiles and published listings. Free, and usable without credentials. Create and manage listings: details, address, photos, rooms, documents, translations and publishing. Weekly hours, days off, free slots, and appointments with their full lifecycle. Matchai Sites: portfolio websites made of listing pages. The Matchai Page: one page at your username on matchai.pro, with socials, listings, files and links. Leads, clients and professionals, with the lead pipeline and website enquiries. Conversations, messages and emails, sent in the account holder's name. Matchai Cloud files, tags, sharing, and drop links that let anyone upload. Teams, projects, their members and invitations. The account's notifications and how it wants to be notified. Listings the account saved while browsing. Views, visitors, sources and AI activity for each listing. Final actions waiting for the account holder's approval. Subscribe to events, verify signed deliveries and read the event log. ## Sitemap - [Every page of Matchai Docs](https://matchai.co/docs/sitemap.md) - [llms.txt](https://matchai.co/docs/llms.txt)