For AI agents

You are an AI agent, or you are building one. You have no Atribu account, no workspace, no API key, and no browser of your own. This page is the whole surface, in the order you need it.

The golden path is the same thirteen steps a human walks. Twelve of them are yours. Exactly one — creating the account — is a person's, and even that happens inside a URL you hand over.

1. Read these first

Discovery documents for the OAuth surfaces, both live and standards-compliant:

https://www.atribu.app/.well-known/oauth-authorization-server   # RFC 8414
https://mcp.atribu.app/mcp                                      # Streamable-HTTP MCP

2. The bootstrap: there is no signup API

Account creation is a human act behind a captcha. The bootstrap is therefore an OAuth hand-off, exactly like connecting Gmail or Cloudflare:

Step by step, with every request and response: API quickstart · MCP quickstart.

3. Call whoami before anything else

curl -sX POST https://mcp.atribu.app/mcp \
  -H "Authorization: Bearer atb_user_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"whoami","arguments":{}}}'

It costs zero units and answers with the workspaces, profiles, currency, PII mode and write-back state the caller actually has. The REST equivalent is GET /api/v1/workspaces, which needs no profile_id — which is exactly why it is the right first call.

4. Bootstrap the objects

curl -sX POST https://api.atribu.app/api/v1/workspaces \
  -H "Authorization: Bearer atb_user_…" -H "Content-Type: application/json" \
  -d '{"name": "My Agency"}'

curl -sX POST https://api.atribu.app/api/v1/profiles \
  -H "Authorization: Bearer atb_user_…" -H "Content-Type: application/json" \
  -d '{"workspace_id": "WORKSPACE_ID", "name": "My Website"}'

curl -sX POST "https://api.atribu.app/api/v1/tracking/keys?profile_id=PROFILE_ID" \
  -H "Authorization: Bearer atb_user_…"

curl "https://api.atribu.app/api/v1/profile/readiness?profile_id=PROFILE_ID" \
  -H "Authorization: Bearer atb_user_…"

Both creates are idempotent — the workspace on (you, name) for a short window, the tracking key on "this profile already has an active one". Retrying after a dropped connection is safe and is not a duplicate.

5. Readiness is your program counter

GET /api/v1/profile/readiness

Twelve steps in golden-path order, each with a status, a why, a next and a docs_url. summary.next_step is the first non-done step — first, not "most important": the order is the priority.

Every non-done step's next is one of two shapes, and the difference is the whole design:

Four hand-off kinds, and each is honest about why: connect (an OAuth consent needs a browser), sign_dpa (a signature forged on someone's behalf is not a signature), checkout (a payment), contact_support (Atribu itself has to change something).

Do not use onboarding_completed for this. It means one thing — a person pressed Finish in the wizard — and every wizard step is skippable. Full detail: Readiness.

6. The hand-off pattern

Give the user this URL. Poll this handle. Continue when it settles.

GET /api/v1/handoffs/{id}

1. Mint through the route for the thing you need — a hand-off with nothing behind it is a URL nobody can complete, so there is deliberately no POST /api/v1/handoffs.
2. Hand the URL over. It is returned only while status is pending. Capture it once and give it to your user; re-poll for status, not for the URL. Whoever holds it can complete it — no Atribu account, no session, no desktop.
3. Poll. An expired hand-off is a 200 with status: "expired", never a 404. A 404 means the id names nothing your workspace minted.

45 minutes by default. Always read expires_at; a kind whose underlying object has its own clock mirrors that clock instead. Full detail: Hand-offs.

7. What is live over MCP

The whole golden path is. tools/list carries real input schemas, readOnlyHint / destructiveHint annotations, resources and prompts (#1062). Start here:

whoami also folds in a readiness rollup — next_step plus the missing_steps — so one free call answers "who am I and what is left". When that forwarded read fails it answers null with a readiness_error naming the cause, never an empty missing_steps that would read as "all done".

The onboarding family (#1058)

Sixteen tools that walk the golden path end to end, grouped by the step they serve:

Every one is a thin wrapper on exactly one /api/v1 route. They forward your bearer and return what the API says; the client, the error map, the write gates and the audit write live in one shared spine rather than sixteen copies. So no tool holds business logic unreachable over REST — which is what makes "drive it over MCP" and "drive it over REST" the same journey rather than two implementations that can drift.

8. Practising against data that is not real (#1069)

curl -sX POST "https://api.atribu.app/api/v1/profiles/demo?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer atb_user_…"

Sixty days of a fictional clinic's Meta traffic, and a Meta CAPI destination that records what it would have sent instead of calling Meta. Over MCP: create_demo_profile / delete_demo_profile. Full detail: Demo profile.

Its own reads show its own money — that is the point — and every read that spans a workspace's profiles leaves it out, so a demo profile can never inflate a pacing aggregate or a leaderboard. DELETE is a hard delete, not an archive (an archived demo would keep answering with its numbers), and deleting nothing answers 200 with deleted: false rather than 404: a workspace with no demo profile is the state you asked for, and a retry must not look like a failure.

9. The skill

If your host is Claude Code, skills/atribu-attribution-skill packages the tool vocabulary, the defaults (cash ROAS, PII masked) and the write-back safety rules. See the skill.

Where to go next