API referenceComing soon

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 basicsCopy link to this section

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.

PaginationCopy link to this section

List endpoints take limit (1 to 100, default 25) and cursor, and return one page:

{
  "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.

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);
}

IdempotencyCopy link to this section

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.

Request idsCopy link to this section

Every response carries a Matchai-Request-Id header, such as req_7Hq2LmZ9xV4c. Log it, and include it when you contact Matchai support.

Errors and rate limitsCopy link to this section

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 page.

Limits apply per connection. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a 429 adds Retry-After. See rate limits.

Final actionsCopy link to this section

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.

How to read an operationCopy link to this section

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:

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.

Download the OpenAPI fileCopy link to this section

The contract behind this reference is an OpenAPI 3.1 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.

ResourcesCopy link to this section