REST API

Every request carries a workspace API key as a bearer token. Create one in Settings → API keys. The key is shown once, at creation: we store only a hash of it, so it cannot be recovered later — if it is lost, revoke it and mint another. Only a workspace owner can manage keys.

curl https://api.macroprimer.com/v1/me \
  -H "Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxx"

• A key addresses exactly one workspace — its own. No parameter selects a tenant.
• A key can never mint, modify or revoke keys. That requires a signed-in owner.
• Keys do not open the dashboard or admin surfaces.
• Keep keys server-side. A key in browser or mobile code is public. Use one key per system, named for that system, so revoking one never breaks the others.

GET /v1/me confirms the key works, names the workspace it addresses, and lists the scopes it holds. It needs no scope — so it is both the right first call and the fastest way to diagnose an unexpected 403.

{
  "api_key": {
    "name": "CI publishing",
    "prefix": "mp_live_a1b2c3d4",
    "scopes": ["articles:read", "articles:write"],
    "expires_at": "2026-11-17T00:00:00+00:00",
    "request_count": 1043
  },
  "workspace": { "id": "c1…", "name": "Acme", "slug": "acme" }
}

Scopes are resource:action. Read and write are independent — articles:write does not grant articles:read. Grant exactly what an integration needs. Wildcards (articles:*, *) are accepted but widen silently as new actions ship, so prefer explicit scopes.

Pagination. List endpoints take limit (1–100, default 25) and offset, and wrap results in a uniform envelope. Page until has_more is false.

{
  "data": [ … ],
  "pagination": { "limit": 25, "offset": 0, "total": 214, "has_more": true }
}

Partial updates. PATCH changes only the fields you send; omitted fields keep their value.

Errors. One envelope everywhere. Branch on error.type, never on the message, which may be reworded.

{ "error": { "type": "forbidden", "status": 403,
             "message": "this API key is missing the required scope: articles:write" } }

Rate limits. Enforced per workspace — not per key, so extra keys do not buy extra budget — in a fixed 60-second window sized by your plan: 60/min on Free, 300/min on Pro, 1,200/min on Business. Every response reports where you stand, so a client can pace itself rather than discover the limit by being refused.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 274
X-RateLimit-Reset: 1787506596     # unix seconds, when the window resets

Over the limit returns 429 with Retry-After in seconds. Honour that value instead of guessing a backoff — it is exactly the time left in the window. Refused requests still count, so hammering while limited keeps the window full.

group_id is the logical document. An article record is one language variant; every translation of it shares a group_id. Sync against group_id, not id. Collections work the same way.

The default language is the source of truth. It defines structure, ordering and the search corpus; other languages overlay text onto it, and anything untranslated falls back — so a locale never shows dead links. Editing the source marks its translations stale, which is your signal to re-translate.

58 operations. The scope each one requires is listed beside it.

Publish from CI.

curl -X POST https://api.macroprimer.com/v1/articles \
  -H "Authorization: Bearer $MACROPRIMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Release 4.2","body":"<p>…</p>","status":"published"}'

Incremental sync. Poll updated_since with the timestamp of your last successful run instead of re-listing everything.

curl -sG https://api.macroprimer.com/v1/articles \
  -H "Authorization: Bearer $MACROPRIMER_KEY" \
  --data-urlencode "updated_since=2026-08-01T00:00:00Z" \
  --data-urlencode "include_body=true" \
  --data-urlencode "limit=100"

Re-translate what has gone stale.

curl -sG https://api.macroprimer.com/v1/articles -H "Authorization: Bearer $KEY" \
  --data-urlencode "limit=100" \
| jq -r '.data[] | select(.translation.stale) | .id' \
| while read id; do
    curl -sX POST "https://api.macroprimer.com/v1/articles/$id/translate" \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"target_langs":["es","fr"]}'
  done