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.

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