REST API

Every public Double Agent route, with the key it needs and what it returns. Most sites only need the script and token checks on the server. Come here when you call the API yourself or export data.

Auth

Base URL: https://api.doubleagent.so. Errors look like { "error": { "code", "message" } }.

Rate limits: Security. Routes the portal uses for team members, billing, usage, account closure and Search Console management are not listed here.

Collection and tokens

Collection telemetry: POST /v1/collect answers with header DA-Telemetry-Accepted: 0 when the event could not be queued for storage (detection still succeeded). POST /v1/check always includes telemetryAccepted: true|false in its JSON. Both only say whether storing the session was queued; they never affect the verdict.

Website data

These routes answer 403 site_not_verified until the site has a verified domain (Claim a domain). Add ?data=test to read only localhost sessions, which works before the domain is verified.

Every session is stored, humans included, and appears in these routes within about 30 seconds. /v1/stats accepts ranges up to 365 days. After a domain claim merges keyless history, data routes answer 503 claim_pending (retry shortly) until it is consolidated.

Filter sessions by campaign with ?utm_source=, ?utm_medium=, ?utm_campaign=, ?utm_term=, ?utm_content=, ?click_id= (for example gclid) or ?source_key= (a campaign row's key, URL-encoded, up to 512 characters; other filters take up to 256). utm_source, utm_medium and the source and medium of a source_key match in any case.

Filter by how the visit arrived with ?channel= (values), and by intent with ?intent= (any intent code, for example task or scrape), ?intent_risk= (low, medium, high) or ?intent_evidence= (an evidence code).

Each GET /v1/sessions row carries intent (or null for sessions stored before it) and feedback: { mine, latest, count }: the caller's own label (null for a secret key), the latest label anyone gave, and how many there are. It is null when labels can't be read; the list still loads.

Channels

visitor.channel is Google Analytics 4's default channel group, worked out from the first touch: paid_search, paid_social, paid_video, paid_shopping, paid_other, display, cross_network, search (Organic Search), social (Organic Social), organic_video, organic_shopping, ai_assistant, email, referral, affiliates, audio, sms, mobile_push, direct, internal (from your own site) and unassigned. Sessions stored before 2026-10-07 may carry paid, every paid visit before the split.

Session detail

GET /v1/sessions/:sid also carries the landing title, what the visitor searched on your site and basic ecommerce:

Pages in journey.pages carry search, title (first page of a page load), item (the product: item_id, item_name, price, currency), qf (query pattern codes, SDK 0.13.0) and forms (form submits by form role, SDK 0.14.0) when known.

Visit attribution

Every session, event and export row carries four roles, each with its own evidence:

Evidence is signed, authenticated, ip, rdns, declared, marker, detected or spoofed. visitor.identity keeps its meaning: the strongest proof for the whole visitor. Filter sessions with ?agent_id=, ?operator= or ?controller_id=; /v1/stats breaks traffic down by each.

Edge hits (/v1/hits) resolve the same roles. A shared published IP list proves only the operator, so a Chrome hit from one has identity: ip and the list's operator but no agent_id, and a declared UA from one (ClaudeBot from an Anthropic address) has detected_by: catalog, not ip_list.

Declared and signed visit identity

A visit can declare an ERC-8004 identity in its User-Agent, for example acme.shopping-assistant/1.0, with an optional registry reference in a comment: (erc8004=eip155:1:0x8004a169fb4a3325136eb29fa0ceb6d2e539a432:22). Double Agent keeps it in visitor.declared_agent. A declaration alone proves nothing.

/v1/collect and /v1/check also check an ERC-8128 request signature (a draft standard) when one is sent. It must be single-use and bound to the URI, method, body, content type and User-Agent or Origin, valid for at most 300 seconds with 30 seconds of clock skew. Plain wallets (EOAs) and deployed ERC-1271 accounts are supported.

The result is in visitor.request_auth: status (verified, invalid or unavailable), the wallet, chain, check time and an optional registry binding (owner, agent-wallet, mismatch, unavailable or not-requested) with the block. /v1/check returns it as requestAuth. null means no signature was sent. A verified signature proves the beacon request, not the browsing it reports, and it never changes the verdict. Edge hits keep declarations only. How an agent signs its requests: Verified agents.

Agents on your site

The agents that visited one site. Auth: sk, or session + ?site=. from and to cover up to 365 days.

Caller identity

Who acted, for whom, proven how: Callers.

Evaluate

POST /v1/evaluate (sk) reports what happened on your server: { sid, subject, observationId, action, outcome, request }, plus optional caller fields. outcome is ok, auth_failed, action_denied or confirmed_trap, and request.url must be on one of the site's verified domains. The body may be up to 16 KB (a PACT proof). Example: Report what happened.

A bad caller field is 400 invalid_caller, a bad delegation 400 invalid_delegation; protocol: "pap" is refused until the Personal Agent Protocol is published. The response adds caller (always):

"caller": { "level": "delegated", "verified_by": "reporter", "failures": [], "principal_hash": "3f…",
            "actor_kind": "agent", "in_grant": "no",
            "grant": { "protocol": "oauth", "grant_id_hash": "9a…", "scopes": ["orders:read"], "access": "read",
                       "expires_at": null, "status": "unverified" } }

The signed token adds lvl (the level) when you sent a caller field, and grant ({ id, protocol, access }, id being the grant id hash) when you sent a delegation. Tokens for requests without caller fields are unchanged. An action outside the grant (in_grant: "no") sends the site's caller.scope_violation webhook.

Agent events

POST /v1/agent-events (the agent's ingest key, see Record your public agent) accepts the caller fields of the recorder: counterparty.authenticated client_id, actor and scopes; counterparty.delegation; counterparty.signature with verified_by: "double_agent" and the forwarded request; access and scope_required on operation.started; insufficient_scope on operation.finished; mandate_ref on transaction.recorded. Shapes and limits: the observe README. A pap delegation, or a proof on any protocol but pact, rejects the event (invalid_counterparty).

Stored operations carry caller_level, caller_verified_by, caller_failures, principal_hash, principal_issuer, client_id, actor_id, grant_id_hash, grant_protocol, grant_scopes, grant_status, access, scope_required, required_scopes (from insufficient_scope), in_grant, scope_violation and intent_evidence.

Sessions and website Callers

Each GET /v1/sessions row and session detail carries caller (null before caller identity): level, verified_by, failures ({ code, words }), principal_hashes, actor_kind, grant (protocol, grant_ids, scopes, access, status) and in_grant. Filter sessions with ?verification_level=, ?principal=, ?grant= (64-hex hashes), ?actor_kind= or ?in_grant=.

GET /v1/callers?from&to (sk, or session + ?site=; range ≤ 90 days): { site, from, to, items, counts, truncated }, one row per actor × principal hash (≤ 500) with actor, level, verified_by, failures, actor_kind, grant, sessions, in_grant_no, intent, first_seen and last_seen (unix seconds). Filters: level, principal, grant, actor_kind, class, intent. An unknown parameter is 400.

Audit

Agent rows: surface: "agent", at, agent_id, operation_id, counterparty_id, kind, method, target, outcome. Website rows: surface: "site", at, site, sid, event_id, actor, action, recommendation, policy_decision. Both: principal_hash, grant_id_hash, grant_protocol, grant_status, access, in_grant, scope_violation, caller_level, caller_verified_by.

Intent

GET /v1/sessions/:sid carries intent: the session's intent over all its pages, { code, confidence, risk, evidence, task_kind, purpose, source, version }, plus paths (up to 5 probe paths, for probe only) and path_count. null for sessions stored before intent. Intent is a tag: it never changes the verdict.

code is one of browse, research, read, task, support, crawl, ai_fetch, monitor, probe, scrape, cred_attack, flood or unknown. task_kind (signup, login, contact, book, purchase, download) is set for task and purpose (search, seo, training, feed, preview) for crawl; both are null otherwise. risk is none for benign intents.

GET /v1/intents?from&to (sk, or session + ?site=; range ≤ 90 days): the site's sessions in the range by class and intent, { total, rows: [{ class, intent, sessions }], kinds: [{ intent, kind, sessions }] } (kinds: task kinds and crawl purposes). Sessions stored before intent count as unknown; edge requests are in /v1/threats and /v1/hits/stats.

Agent analytics

Session auth. Every route is under /v1/managed-agents/:id, where :id is one of your account's agents (another account's agent is 404). The caller needs agents.read, except where the table says otherwise.

Shared query parameters:

• env: live or test.
• The range is either range (24h, 7d, 30d or 90d) or from and to (ISO-8601 instants), never both (400 invalid_range).
• The comparison is compare (prev, the default; week, month, off or custom) and compare_from (YYYY-MM-DD, with compare=custom only).

Lists page with the opaque cursor from the previous page's next. A cursor is bound to the query that made it; reused with a different query it is 400 invalid_cursor. An unknown query parameter is 400.

Closed days are read from daily rollups; yesterday and today are read from raw data. Test operations are listed but never counted.

PATCH /v1/managed-agents/:id (agents.manage) takes webhook_url (https) and webhook_secret (16–200 characters) for the agent's caller.scope_violation webhook; null clears either. The agent view shows webhook: { configured, url }, never the secret.

To add an agent, its sources and ingest keys, see Record your public agent.

Agent revenue

Owners and Admins hold agents.revenue.read; other roles need it granted. Without it, the routes below are 403, and the analytics routes above leave money out: no money field, and the Overview panel says revenue: { locked: true }.

Amounts are minor units of the account currency (GET /v1/me), with up to 4 decimals. Every response with money names its currency and currency_exponent. Revenue is charges plus refunds (refunds are negative), never failed ones; cost is recorded costs plus fees; margin is revenue minus cost. Money that no exchange rate covers is counted in unconverted and never summed. Money converted into a former account currency is re-converted at its own day's rate and counted in other_currency.

basis picks which money counts: settled, reported (reported and settled) or all (also estimated, the default). Transactions and costs are kept 13 months.

With agents.revenue.read, these routes also carry money:

A task's or operation's money adds every basis: { currency, currency_exponent, in_account_currency, revenue, cost, transactions, settlement, unconverted, other_currency }. in_account_currency is false for money converted before the account currency changed. Its transactions count stops at 64 (16 for an operation), so it can be lower than the task's transactions list.

Agent directory

Public: no key, CORS *. Each IP can make 60 requests a minute across these routes. Tighter limits apply to check (10 a minute), submissions (10 a minute) and reviews (30 a minute).

Every agent with its own card, for agents: GET /v1/directory/agents?card=with&status=live&limit=50, paged with cursor.

The same data, for people: /agents/.

Accounts and auth

Sites, domains, keys

Session auth. Viewers can only read.

Adding or removing an ERC-8004 identity needs the Owner or Admin role. POST takes agent_name (for example acme.shopping-assistant) and token_id (a decimal string), with optional chain_id, registry_address, reviewers (up to five addresses), reputation_registry, tag1 and tag2. Ethereum mainnet and its official registry are the defaults, and Double Agent picks the RPC endpoint. A new association answers 201, a refresh 200, each with id, snapshot (block, owner, wallet and registration URI), association: "site-configured", visit_binding: "unverified" and updated_at. GET returns { identities } and DELETE answers 204. A failed chain read is 503. Saving an association never authenticates a visitor or changes detection. The same from the command line: CLI.