REST API (v1)

Base URL: https://signal.ambit.agency. JSON in, JSON out. Account endpoints need Authorization: Bearer sk_live_... (create keys in the dashboard under API keys). Errors return {"ok": false, "error": "..."} with a 4xx status.

Sites

`GET /v1/sites`

List the account's sites.

{"ok": true, "sites": [{"site_id": "st_...", "domain": "example.com", ...}]}

`POST /v1/sites`

Body {"domain": "example.com"}. Returns the public site_id and the server secret (shown once).

{"ok": true, "site_id": "st_...", "domain": "example.com", "secret": "ss_..."}

409 if the domain is already registered to a Signal account.

`GET /v1/sites/{site_id}/status`

Install check over the last 24 hours.

{"ok": true, "receiving": true, "last_event_ts": 1790170000.0, "events_24h": 42,
 "classes_seen": {"human": 30, "ai_crawler": 8, "ai_fetch": 4}, "sources_seen": {...}}

`GET /v1/sites/{site_id}/snippet?platform=<key>`

Install steps, files and env for one platform. Platform keys: cloudflare, vercel-next, express, astro, sveltekit, netlify, wordpress, nginx, caddy, js-tag, webflow, squarespace, wix, shopify. The secret is never re-revealed; the snippet carries a placeholder.

`GET /v1/sites/{site_id}/report?days=30`

The full Signal report for the site (days 1 to 400): by_kind, tiers, ai_by_provider, ai_fetch_pages, ai_landings, crawl_to_refer, audience breakdowns, inquiries.

Outcomes

`POST /v1/outcomes`

See outcomes. Bearer (trusted: value and status accepted) or browser mode (public site_id + matching Origin; value and status ignored).

Collection endpoints (used by collectors, not called by hand)

Endpoint	Auth	Used by
`POST /ingest`	HMAC: `X-Ambit-Site`, `X-Ambit-Timestamp`, `X-Ambit-Signature: v1=hex(HMAC-SHA256(secret, "<ts>.<body>"))`	server collectors (max 256 KB, 500 events, timestamp within 300 s, replay-protected)
`POST /v1/collect`	public `site_id` + Origin must match the site's domain	JS tag

Rate limits

Outcomes with an API key: 600 per account per minute. MCP: 60 requests per key per minute. Browser outcomes and JS-tag collection are rate limited per visitor. Signed ingest: 120 posts per minute per site. A 429 means back off and retry.

Health

GET /v1/health returns {"ok": true}.