Workspaces & Profiles

A workspace is the top-level container: billing, members, branding, API keys. A profile is one advertised business inside it — one set of ad accounts, one CRM, one tracker, one attribution answer. Every profile-scoped route on this API answers for one profile.

Most businesses need one workspace and one profile. An agency needs one workspace and a profile per client.

Creating them without a browser

POST /api/v1/workspaces

Two unrelated ways to call it, sharing one URL — the same shape POST /api/v1/profiles uses.

• Session bearer — a Supabase session token or an atb_user_… MCP token: you create your own workspace and become its owner. Body: {"name": "Acme", "timezone": "America/Santiago", "plan": "growth"}.
• HTTP Basic — a registered consumer app creating a bare workspace for one of its users, identified by email. No profile and no delegation grant are created; follow with your own POST /api/v1/profiles.

plan defaults to starter (Free). growth / agency immediately write a trialing subscription at that plan's real limits rather than waiting for the first profile to bootstrap Free — so an agent that creates the workspace before its first POST /profiles does not silently sit on Free believing it asked for Growth. enterprise is sales-led and is not accepted here.

checkout — the plan you asked for, paid for in the same round trip

A growth or agency create returns a checkout hand-off alongside the new workspace, so an agent that knows which plan it wants never mints one separately:

{
  "data": {
    "workspace_id": "…",
    "name": "Acme",
    "created": true,
    "checkout": {
      "id": "0f2f6b0a-9a2c-4f4e-9a1e-6f7f2a5c3b21",
      "url": "https://www.atribu.app/h/9tQ2mB1x…",
      "expires_at": "2026-09-05T11:30:00.000Z"
    }
  }
}

Hand checkout.url to the person who pays and poll GET /api/v1/handoffs/{id} — it is an ordinary checkout hand-off, the same object POST /api/v1/workspaces/{workspaceId}/checkout-session mints. See Billing.

POST /api/v1/profiles

POST /api/v1/profiles has two branches. The app-credential branch provisions a dealer end to end (see Partners & OAuth apps); the session branch is what a person or their agent uses for their own next client. A profile creation is refused with plan_limit_reached once the workspace's active_profiles allowance is spent — that limit is enforced on every creation path, so an agent that plans to create ten profiles should read the subscription first.

Retiring a workspace

DELETE /api/v1/workspaces/{workspaceId}

Owner only, and terminal — there is no un-archive. A workspace created by mistake, or a throwaway one an agent made while exploring, is retired with this call.

"Delete" means ARCHIVE, and the response says so. A workspace that has ever exported holds conversion_exports rows, and a database trigger refuses to let any path erase them — they are the record of what Atribu transmitted on your customers' behalf. So the call stamps archived_at, removes every membership, revokes pending invitations, archives every profile and purges its tracking, attribution and spend data, revokes the workspace's API keys and pauses its webhook subscriptions. What survived is in counts.retained_*.

{
  "data": {
    "workspace_id": "873efefe-5fe0-44d5-8f67-0d3967855ff6",
    "archived": true,
    "archived_at": "2026-09-06T14:42:11.547Z",
    "counts": {
      "profiles_archived": 1,
      "memberships_removed": 1,
      "invitations_revoked": 0,
      "api_keys_revoked": 0,
      "webhook_subscriptions_paused": 0,
      "retained_conversion_exports": 1,
      "retained_signal_audit_rows": 3
    },
    "profiles_purged": 1
  },
  "meta": { "workspace_id": "873efefe-5fe0-44d5-8f67-0d3967855ff6" }
}

A session bearer, or an atb_user_… token whose grant covers workspaces:write — a default mcp:read token is refused. An atb_live_ API key cannot call it: a key is minted for exactly one profile and belongs to no workspace. A member who is not an owner gets 403; a non-member gets 404, the same answer an unknown id gets, so the status code never confirms that a workspace exists.

After archiving, every workspace-scoped route answers 404 for it, it is absent from GET /api/v1/workspaces and from MCP whoami, and a pending invitation to it can no longer be accepted.

Reading what you can reach

GET /api/v1/workspaces is the right first call for a user credential: it needs no profile_id, and it tells you which workspaces the person behind the token belongs to. GET /api/v1/workspaces/{workspaceId}/profiles then lists the profiles inside one.

Everything under /workspaces

The workspace is also the grain for cross-profile analytics (Top Performers, creative patterns, experiments, pacing), for agency reporting, and for the admin surfaces a console needs. Those routes live under /workspaces/{id}/… because they are workspace-scoped, and they are explained where the feature is: Top Performers and creative reads, reports, credentials.

Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.

Next steps