Agent-driven setup

An agent can start a Datalyr signup, prefill the workspace details, and verify the install end to end. A person pays, approves scripts, and mints keys. This page is the exact flow across that boundary.

The four hand-offs

Step	Who	Surface
1. Start the signup	Agent	`POST /v1/signup`
2. Verify the email and pay	Person	Email link, then Autumn-hosted Stripe checkout
3. Install tracking and connect sources	Person, or agent with a scoped key	Dashboard, or `POST /v1/rules` and `POST /v1/links`
4. Confirm it works	Agent	`GET /v1/onboarding`, `get_workspace`

POST /v1/signup is the only Datalyr API route that needs no key. It sends one verification email and returns one field.

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"}'

{ "status": "verification_sent" }

Nothing is created by this call. The account row is written when the recipient opens the link, from their own browser. An unopened link leaves no account behind.

Fact	Detail
Response	Always `{"status": "verification_sent"}`, for a new address and an existing one alike. Infer nothing about the address from it.
Rate limit	Capped per client IP and per email address. `429` carries `Retry-After` in seconds.
`503`	The email was not sent. Retry after the delay.
`400`	Your request was wrong. The `error` field names the field to fix.
`workspace_name`, `primary_domain`	Held for 24 hours and used to prefill the form the person lands on.

Step 2: the person verifies and pays

The link signs the person in and lands them on the new-workspace form, prefilled with the name and domain you sent. They pick a plan and complete a Stripe checkout hosted by our billing provider. The workspace row is created when that payment settles. Until then no workspace exists, no API key exists, and no data can be sent or read. Give the person the signup email address you used and tell them to expect the link. Do not ask them for card details, and do not accept any.

Step 3: setup

Ask the person for two things once their workspace is live.

Install tracking. Point them at Install web tracking or Mobile.
Create a named API key with the scopes you need. See API keys.

With a scoped key you can create conversion rules and trackable links directly, and propose container scripts for review. Each route names the scope it needs.

Step 4: confirm it works

GET /v1/onboarding needs an Agent key, so it answers only after step 2. 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.
Mint an API key	An owner or admin creates named keys in the dashboard and grants each scope explicitly.
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

Workspace

Conversion rules

Trackable links

Exports

The four hand-offs

Step 2: the person verifies and pays

Step 3: setup

Step 4: confirm it works

What an agent cannot do

​The four hand-offs

​Step 1: start the signup

​Step 2: the person verifies and pays

​Step 3: setup

​Step 4: confirm it works

​What an agent cannot do

The four hand-offs

Step 1: start the signup

Step 2: the person verifies and pays

Step 3: setup

Step 4: confirm it works

What an agent cannot do