AuthenticationComing soon

Every request to the Matchai API acts for one Matchai account. There are two ways to get the credential that proves it, and the right one depends on whose account you are working with.

Two ways inCopy link to this section

Both go in the same header:

Authorization: Bearer matchai_…

An OAuth access token is sent the same way, in place of the key.

What a request can doCopy link to this section

A request can do what the account holder can do in Matchai, under the same rules and permissions, and nothing more. Two things narrow it further:

• Scopes limit which parts of the account the credential can touch.
• Final actions wait for the account holder's approval, unless they allowed your app to run them.

GET /v1/me/connection (getConnection) tells your app how it is connected: the app, the scopes granted, auth_type (api_key or oauth), approval_mode (ask_me or allowed) and whether the connection is in test mode.

ScopesCopy link to this section

Each operation in the API reference lists the scopes it needs. Ask only for what your app uses: a professional is more likely to press Allow when the list is short and every line makes sense.

When a credential lacks a scope, the call fails with 403 and the code scope_missing, and the message names the scope. For a key, create a new key that has the scope and revoke the old one. For an OAuth connection, send the professional through your app's connect flow again, so they can agree to the longer list.

A few operations need no scope because they only work with what is already public, such as looking up a professional's published profile. They are marked Free in the reference, and a key or token is optional for them.

Final actionsCopy link to this section

Four kinds of action are final: sending something to another person, publishing something to the public, paying, and deleting the account's content. The Matchai Assistant always asks before it does any of them, and the API holds your app to the same rule. Each final action is marked Final action in the reference.

The account holder chooses how your app handles them, per connection:

Anything that is not a final action runs under the credential's scopes, as the same edit would in the app: reads, drafts, and changes to the account holder's own records. Removing your own app's configuration, such as a webhook subscription, is not a final action either.

Write your app for both settings. The account holder can change the setting at any time, so never assume which one you will get.

Follow an approvalCopy link to this section

A final action under Ask me answers 202 and does nothing yet:

{
  "status": "pending_approval",
  "approval_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
  "approval_url": "https://matchai.co/approvals/1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
  "expires_at": "2026-10-25T13:05:00Z",
  "summary": "Send a message to Julien Bouchard"
}

An approval has one of five statuses:

GET /v1/approvals (listApprovals) lists the requests your connection has made, and takes a status filter.

Send an Idempotency-Key with every final action. If your request times out and you repeat it with the same key, you get the same pending approval back instead of a second one.

This example publishes a listing and handles both settings:

import { randomUUID } from 'node:crypto';

const response = await fetch(`https://api.matchai.co/v1/listings/${listingId}/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
});

if (response.status === 202) {
  // Ask me: nothing has happened yet.
  const pending = await response.json();
  console.log(`Waiting: ${pending.summary}`);
  console.log(`The account holder can answer at ${pending.approval_url}`);
} else if (response.ok) {
  // Allowed: the listing is published now.
  const listing = await response.json();
  console.log(`Published at ${listing.url}`);
} else {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

Energy limitsCopy link to this section

Some actions spend Matchai Energy, the way the AI features do in the app: writing a listing with AI, editing photos, translating, drafting with AI, sending an email, and messages that go out by text. The reference marks each of them, and says how heavy the action is: light, moderate, heavy, or it varies.

• The API never shows Energy as a number. GET /v1/me returns its state: full, comfortable, low or empty.
• A call that needs more than is left does nothing. It answers 402 with the code insufficient_energy, and nothing is spent.
• The account holder can set an Energy limit for each connection, so a runaway script stops at a ceiling they chose. When your connection reaches it, calls that spend Energy answer 402 with the code energy_limit_reached, and GET /v1/me/connection reports energy_limit_reached: true.

Show the message of a 402 to the person: it says what happened and what to do next. See errors.

Ending a connectionCopy link to this section

A connection ends in one of three ways, and each one stops every credential that belongs to it:

• The professional presses Disconnect on the Connectors page.
• You revoke an API key.
• Your app calls DELETE /v1/me/connection (disconnect). It ends the connection as if the professional had pressed Disconnect, and deletes nothing in the account.

After a connection ends, its webhook subscriptions are turned off and its requests answer 401. Treat that as "connect again", not as an outage.

Test modeCopy link to this section

An app that is connected only to its own developer's account is in test mode. Test connections are not billed, and the events they produce carry test_mode: true. Create a Matchai app explains how it works, and who pays once other professionals connect.