API overview

The Meerkats API lets your own code and the apps you build on Meerkats read business context and manage automations: query any metric in the catalog, list and create rules, approve or reject proposals, run agents, and check sync status. It is the same surface the app uses, so anything you can see in Meerkats you can read over the API.

Create an API key#

Keys are issued under an app. An app is a product you build on your data, with its own branding and its own users; a key belongs to the app and is scoped to the workspaces you choose.

1. Open Apps

   Select your name at the bottom of the sidebar, then Apps, then Create app. Give it a name; add a logo, colours and support email if your users will see a login screen.

2. Create a key

   Inside the app, create a key. Choose read or write scope (write implies read) and tick the workspaces the key may access.

3. Copy it once

   The key starts with mk_live_ and is shown once. Store it on your server. Never put it in a browser or a mobile app.

Authentication#

Every call carries your API key. Data calls also carry a token for the end user who is asking, so Meerkats knows which of your users it is and records their actions against them.

If you omit X-Workspace-Id, the key’s first workspace is used. Tokens are short-lived; there is no refresh endpoint, so log the user in again when a call returns 401.

A first request#

1. Log a user in
   curlCopy

   curl -X POST https://partners.meerkats.ai/api/public/v1/auth/login \
     -H "X-API-Key: $MEERKATS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "email": "user@example.com", "password": "…" }'
   
   → { "success": true, "token": "<jwt>", "user": { … } }

2. List the workspaces the key can see
   curlCopy

   curl https://partners.meerkats.ai/api/public/v1/workspaces \
     -H "X-API-Key: $MEERKATS_API_KEY" \
     -H "Authorization: Bearer $TOKEN"
   
   → { "success": true, "workspaces": [ { "id": "…", "name": "Northwind Growth", "is_default": true } ] }

3. Query a metric
   curlCopy

   curl -X POST https://partners.meerkats.ai/api/public/v1/metrics/query \
     -H "X-API-Key: $MEERKATS_API_KEY" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Workspace-Id: $WORKSPACE_ID" \
     -H "Content-Type: application/json" \
     -d '{ "metrics": ["real_roas", "campaign_spend"], "groupBy": ["ad_row__platform"], "dateRange": "last_7_days" }'
   
   → { "success": true, "metrics": [...], "group_by": [...], "row_count": 2, "rows": [ { "ad_row__platform": "meta", "real_roas": 2.8, "campaign_spend": 3120 }, … ] }

Call GET /metrics/catalog first to learn which metric and dimension names your workspace accepts; unknown names return 400.

Endpoints#

Full request and response shapes are in the OpenAPI document. The pages on rules, approvals, agents and metrics show the bodies in context.

The query body#

The workspace comes from the headers, never from the body. The response has metrics, group_by, row_count and rows; each row has one key per requested metric and dimension.

Scopes, limits and errors#

Scopes#

A key has read or write scope. Read endpoints need read; anything that creates, changes, approves, runs or deletes needs write. Write implies read. A call outside the key’s scope or workspaces returns 403.

Rate limits#

120 requests a minute per key by default, configurable per key. Over the limit returns 429; back off and retry.

Errors#

Every error has one shape:

{
  "success": false,
  "error": "Unknown metric: real_roas_7d",
  "statusCode": 400,
  "timestamp": "2026-10-02T09:14:03.000Z"
}

Good practice#

• Keep the API key on your server. Proxy calls from your front end through your own backend, so the key never reaches a browser.
• Send X-Workspace-Id on every data call, even with one workspace. It makes the call explicit in the Activity log.
• Cache /metrics/catalog; it changes only when definitions change.
• Prefer presets like last_7_days to custom dates; they follow the workspace time zone.
• Record the timestamp from error bodies when you report an issue.

Troubleshooting#