Agent API

Sift is agent-native. An AI coding agent can create an account, register a site, inject the snippet, and read stats without a human clicking anything.

There is no separate agent tier. An agent account is an account.

DiscoveryCopy Anchor Link

Two machine-readable entry points:

• https://sift.agentonboard.xyz/auth.md — the API contract in Markdown.
• https://sift.agentonboard.xyz/.well-known/auth.md — the same document at the conventional location.

Point an agent at either one before it writes code.

The tokenCopy Anchor Link

Every request carries a short-lived RS256 JWT:

Authorization: Bearer <token>

Tokens are minted by AgentOnboard for the audience sift.agentonboard.xyz:

get_token(domain: "sift.agentonboard.xyz")

Tokens are short-lived by design. Do not cache them across a long task; mint a fresh one when a call returns 401.

The flowCopy Anchor Link

1. get_token(domain: "sift.agentonboard.xyz")
2. GET  /api/v1/agents/sites
      └─ 403 ACCOUNT_REQUIRED? → POST /api/v1/agents/signup, then retry
3. POST /api/v1/agents/sites        { domain, timezone }
      └─ returns the snippet
4. Inject the snippet into the site
5. GET  /api/v1/agents/sites/{domain}
      └─ verified: true once a pageview arrives
6. GET  /api/v1/agents/stats/{domain}?period=7d

Step 2 before step 3 is deliberate. It tells the agent whether an account exists without creating one as a side effect.

Identity mappingCopy Anchor Link

The verified email in the token maps to a Sift account. Same email, same account — whether a human signed up or an agent did.

That means an agent working for an existing user lands in that user's sites, not a new empty account. It also means an agent cannot see another account's sites.

Retry rulesCopy Anchor Link

These are part of the contract, not suggestions.

Two rules matter more than the table:

• Never retry a 403 ACCOUNT_REQUIRED without calling /signup first. It cannot succeed.
• Never retry a 401 in a loop. One refresh, then stop.

What an agent should not doCopy Anchor Link

• Do not create an account for an email that already has one. /signup is idempotent, but the check in step 2 avoids the call entirely.
• Do not guess domains. Read the site list.
• Do not write events. There is no ingestion API, and fabricating traffic would make the data worthless.
• Do not delete a site to "clean up" a test. Delete the test site you created, and nothing else.

ExampleCopy Anchor Link

Mint a token with the AgentOnboard get_token tool for sift.agentonboard.xyz, then use it as $TOKEN:

curl -s https://sift.agentonboard.xyz/api/v1/agents/sites \
  -H "Authorization: Bearer $TOKEN"

curl -s -X POST https://sift.agentonboard.xyz/api/v1/agents/sites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

See API reference for every endpoint and response shape.