Agent-driven setup

An agent can start a Datalyr signup, hand the person one link, collect a read key, and verify the install end to end. A person pays and clicks Approve. This page is the exact flow across that boundary.

The hand-offs

Step	Who	Surface
1. Start the signup	Agent	`POST /v1/signup`
2. Open the checkout link and pay	Person	`checkout_url`, then Autumn-hosted Stripe checkout
3. Approve the read key	Person	The approval card on the page after payment
4. Collect the key	Agent	`GET /v1/signup/{id}`, then `GET /v1/keys/requests/{id}`
5. Install tracking and connect sources	Person, or agent with a scoped key	Dashboard, or `POST /v1/rules` and `POST /v1/links`
6. Confirm it works	Agent	`GET /v1/onboarding`, `get_workspace`

POST /v1/signup is the only Datalyr API route that needs no key. Send key_request to get a read key once the person pays.

curl -X POST https://api.datalyr.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","workspace_name":"Ada Labs","primary_domain":"ada.dev","plan":"growth","key_request":{"name":"Setup agent","scopes":["datalyr:read"]}}'

{
  "status": "checkout_ready",
  "signup_id": "7b0c7a52-5d0e-4a51-9d5e-3f1f4a2b9c10",
  "signup_secret": "dl_signup_…",
  "checkout_url": "https://www.datalyr.com/signup/continue#…",
  "status_url": "https://api.datalyr.com/v1/signup/7b0c7a52-5d0e-4a51-9d5e-3f1f4a2b9c10",
  "expires_at": "2026-10-02T12:00:00.000Z",
  "key_request": {
    "request_id": "c41e0f3a-2b7d-4f7e-8a0c-6d9b1e2f3a4b",
    "poll_url": "https://api.datalyr.com/v1/keys/requests/c41e0f3a-2b7d-4f7e-8a0c-6d9b1e2f3a4b"
  }
}

Store signup_secret. We return it once and never again. It authorizes the status reads in step 4 and nothing else.

Field	Detail
`email`, `workspace_name`	Required. The email belongs to the person who pays and owns the workspace.
`primary_domain`	Optional. Reduced to its hostname.
`plan`	Optional. `growth`, `scale`, or `performance`. The person picks one on the checkout page when you omit it.
`key_request`	Optional. `scopes` must be exactly `["datalyr:read"]`. Anything else returns `400` with `scope_not_allowed_at_signup`.
Response	The same shape for a new address and an existing one. Infer nothing about the address from it.
`expires_at`	The checkout link works for 7 days, until the person pays.
Rate limit	Capped per client IP and per email address. `429` carries `Retry-After` in seconds.
`503`	The signup did not start. Retry after the delay.

Nothing is created by this call except the pending signup. No account, workspace, or key exists until the person pays.

Step 2: the person pays

Give the person checkout_url. It opens a page with the workspace name, the domain, the plan, and their email, which they can edit. They select Continue to payment and complete a Stripe checkout hosted by our billing provider. Paying is the verification. We also send a verification email as a backup path, and its link opens the same checkout page. Do not ask the person for card details, and do not accept any.

Step 3: the person approves the key

The page after payment shows an approval card for the key you requested in step 1. It names the scope, the workspace, and the requester. The person selects Approve or Deny. An address that already has a Datalyr account gets the workspace, but no session in the paying browser. That person signs in from the email link, then sees the card.

Step 4: collect the key

Poll the status URL with the signup secret until status is paid.

curl https://api.datalyr.com/v1/signup/7b0c7a52-5d0e-4a51-9d5e-3f1f4a2b9c10 \
  -H "Authorization: Bearer dl_signup_…"

`status`	Meaning
`pending_email`	The person has not continued to payment yet.
`pending_payment`	Checkout started. Payment has not settled.
`paid`	The workspace exists. The body adds `workspace_id` and `key_request.status`.
`expired`	7 days passed without payment. Start a new signup.

An unknown id and a wrong secret both return the same 404. This route never returns a key. Then poll poll_url with the same signup secret. The first poll after Approve returns the key in key. Later polls return key_id and key_prefix without it. See Authentication for every status.

Step 5: setup

Ask the person to install tracking. Point them at Install web tracking or Mobile. To create conversion rules or trackable links, file a key request for the write scope you need. The workspace owner approves it. See API keys.

Step 6: confirm it works

GET /v1/onboarding needs a key, so it answers only after step 4. Read next_steps, drive one item, then read it again.

curl https://api.datalyr.com/v1/onboarding \
  -H "Authorization: Bearer dk_agent_..."

{
  "workspace": { "id": "wsPublic01", "created": true, "active": true, "plan": "pro" },
  "tracking": {
    "first_event_seen_at": null,
    "last_event_seen_at": null,
    "sdk_detected": [],
    "events_last_30d": 0
  },
  "connections": [{ "platform": "shopify", "status": "active" }],
  "next_steps": ["Install tracking: add the Datalyr web snippet, a mobile SDK, or the Shopify app, then re-check this endpoint."]
}

Field	How to read it
`first_event_seen_at`	`null` means this workspace has never received an event. It covers all time, not a window.
`sdk_detected`	Event transports seen in the last 30 days. `web` proves the browser snippet works.
`connections[].status`	Anything other than `active` needs a person to reconnect that source.
`next_steps`	Ordered by dependency. Work the first item first.
`503`	Tracking status is unknown. It is not a report of zero events. Retry.

Confirm the install by watching first_event_seen_at change from null to a timestamp after the person adds the snippet. A 200 on the key alone proves only that the key works.

What an agent cannot do

These four are human actions by design, not gaps to work around.

Action	Why
Pay	Checkout runs in the person’s browser with their own payment credential. No API accepts card details, and no flag skips the charge.
Create a workspace before payment	Only the paid-checkout path writes a workspace row. `POST /v1/signup` cannot reach it.
Grant itself power	Every key needs a person’s Approve or an OAuth consent. A key never mints a key.
Publish a container script	Scripts are propose-only. `POST /v1/scripts/proposals` records a draft, and an owner or admin approves it in the dashboard.

MCP has no signup tool for the same reason. MCP needs an OAuth token, which needs an account that already exists. Use POST /v1/signup before that point, and get_onboarding_status after it.

Agents and MCP

API Reference

Analytics

Events and users

Attribution and revenue

Cohorts and funnels

Metrics

Query

Workspace

Keys and approvals

Conversion rules

Trackable links

Saved reports

Dashboards, analyses and share links

Session replay

Exports

The hand-offs

Step 2: the person pays

Step 3: the person approves the key

Step 4: collect the key

Step 5: setup

Step 6: confirm it works

What an agent cannot do

​The hand-offs

​Step 1: start the signup

​Step 2: the person pays

​Step 3: the person approves the key

​Step 4: collect the key

​Step 5: setup

​Step 6: confirm it works

​What an agent cannot do

The hand-offs

Step 1: start the signup

Step 2: the person pays

Step 3: the person approves the key

Step 4: collect the key

Step 5: setup

Step 6: confirm it works

What an agent cannot do