Account and workspaces.

Check your plan and usage, create a workspace per client, and mint a key for each one. Everything here works over the API, so after your first key you never need the dashboard.

How workspaces scope a request

• Every key belongs to one workspace: the one it was minted in. Watchlists, Meta connections and Meta writes act on that workspace.
• Send X-Workspace-Id to act on another workspace you belong to with the same key. A workspace you're not a member of returns 403 workspace_forbidden.
• Each workspace has its own Meta connection, so one agency key can run several clients' ad accounts side by side. See Connect Meta.

curl https://api.brandmov.com/api/v1/meta/connection \
  -H "Authorization: Bearer bm_live_your_key_here" \
  -H "X-Workspace-Id: 7e21b0c3-5d4a-4f9b-8a1e-2c3d4e5f6a7b"

Roles, lowest to highest: viewer, editor, admin, owner. Reads need viewer. Connecting Meta, pinning an ad account and renaming need admin. Archiving needs owner.

Get your account

Plan, credits, limits and how many AI calls (ad copy, hooks, angles) you have left today. The daily AI budget resets at midnight UTC.

curl https://api.brandmov.com/api/v1/account \
  -H "Authorization: Bearer bm_live_your_key_here"

{
  "uid": "Hq3...",
  "email": "[email protected]",
  "workspace_id": "1c9d2f4a-7b6e-4a2f-9c3d-8e5f1a2b3c4d",
  "usage": {
    "plan": "ltd_eb4",
    "credits_used": 40,
    "credits_total": 1000,
    "watchlist_used": 12,
    "watchlist_limit": 50,
    "...": "..."
  },
  "ai_calls": { "used_today": 12, "daily_cap": 200, "remaining_today": 188 }
}

Workspaces

List

Every workspace you can act in, with your role, whether it's the one this request resolved to, and whether Meta is connected.

{
  "workspaces": [
    {
      "id": "1c9d2f4a-7b6e-4a2f-9c3d-8e5f1a2b3c4d",
      "name": "Acme Growth",
      "role": "owner",
      "current": true,
      "meta_connected": true
    },
    {
      "id": "7e21b0c3-5d4a-4f9b-8a1e-2c3d4e5f6a7b",
      "name": "Client B",
      "role": "admin",
      "current": false,
      "meta_connected": false
    }
  ]
}

Create

Returns 201. Counts against your plan's workspace limit; over it you get 402. Archived workspaces don't count.

curl -X POST https://api.brandmov.com/api/v1/account/workspaces \
  -H "Authorization: Bearer bm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Client C"}'

{
  "id": "9a8b7c6d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "name": "Client C",
  "role": "owner",
  "archived": false
}

Rename

Archive and restore

Owner only. Archiving frees a slot under your plan limit; restoring takes one back, so it returns 402 when you're at the limit. Keys minted in an archived workspace stop working on the other endpoints (403 workspace_archived) but still work here, so you can restore it or mint a key elsewhere.

API keys

Mint

Returns 201 with the plaintext key. It is shown once; we only store a hash. Up to 25 active keys per account.

curl -X POST https://api.brandmov.com/api/v1/account/api-keys \
  -H "Authorization: Bearer bm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "client-c-n8n", "workspace_id": "9a8b7c6d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"}'

{
  "id": "e3b0c442...",
  "name": "client-c-n8n",
  "prefix": "bm_live_4f1b...",
  "workspace_id": "9a8b7c6d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "created_at": "2026-10-02T09:14:03+00:00",
  "last_used_at": null,
  "revoked_at": null,
  "key": "bm_live_4f1b2c...e9"
}

List

Your keys across every workspace, newest first. Never includes the plaintext.

Revoke

Immediate: the next request with that key returns 401. A key can mint other keys, so if one leaks, list your keys and revoke anything you don't recognise.

Errors

Account, workspace and Meta connection endpoints return a stable code you can branch on:

{
  "detail": {
    "error": {
      "code": "workspace_role",
      "message": "This action needs the admin role or higher in the workspace."
    }
  }
}

• 402: plan limit or feature not on your plan.
• 403: workspace_forbidden, workspace_role, workspace_archived, api_disabled.
• 404: workspace_not_found (also returned for workspaces you don't belong to), key_not_found.
• 409: no_workspace, already_archived, not_archived, key_limit, already_revoked.
• 422: invalid body, e.g. invalid_name.