API quickstart

You have a Driftstack account and want to run your first browser session via the API. This page is a 60-second start. For the full surface, see the API reference.

1. Get an API key

Sign in to the dashboard → Settings → API keys → Create. You'll see a single full-string key starting with ds_live_. Copy it now — we only store the hash, so we can't show it again. If you lose it, revoke and mint a new one.

Pick the narrowest scope that fits your need:

• read — list sessions, fetch session metadata.
• write — start sessions, modify profiles.
• account_owner — full account control.

2. Health-check that the key works

curl -H "Authorization: Bearer $DRIFTSTACK_API_KEY" \
  https://api.driftstack.dev/v1/account/me

→ 200 OK
{
  "id": "acc_…",
  "email": "[email protected]",
  "name": "Your Name",
  "tier": "api_starter",
  "status": "active",
  "timezone": "Europe/Amsterdam",
  "concurrent_session_cap": 2,
  "concurrent_session_active": 0,
  "profile_cap": 25,
  "profile_count": 0,
  "mfa_enrolled": false,
  "teams": [],
  …
}

A 401 here means the key is wrong, malformed, or revoked. Check the dashboard. The response is a flat object — no {"account": …} envelope.

3. Start your first session

curl -X POST \
  -H "Authorization: Bearer $DRIFTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "archetype": "default",
    "purpose": "production_customer",
    "label": "first-session"
  }' \
  https://api.driftstack.dev/v1/sessions

→ 201 Created
{
  "id": "ses_…",
  "account_id": "acc_…",
  "api_key_id": "key_…",
  "status": "creating",
  "archetype": "default",
  "purpose": "production_customer",
  "label": "first-session",
  "metadata": null,
  "created_at": "2026-05-12T12:00:00.000Z",
  "updated_at": "2026-05-12T12:00:00.000Z",
  "last_state_at": null,
  "destroyed_at": null
}

The session id prefix is ses_. Status moves through creating → ready → busy → destroyed (or errored on failure). The response is a flat session object (no envelope). Open the live-view stream in the dashboard at https://app.driftstack.dev/sessions/<id>.

To drive the session to a URL after it's running, use POST /v1/sessions/<id>/navigate with {"url": "https://example.com"} — the session-create call itself doesn't take a target URL.

4. Watch the session progress

curl -H "Authorization: Bearer $DRIFTSTACK_API_KEY" \
  https://api.driftstack.dev/v1/sessions/ses_…

→ 200 OK
{ "id": "ses_…", "status": "ready", … }

Poll every 5 seconds is fine for small workloads. For production traffic, subscribe to webhooks (see POST /v1/webhooks).

5. Capture artifacts during the session

curl -X POST -H "Authorization: Bearer $DRIFTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "screenshot"}' \
  https://api.driftstack.dev/v1/sessions/ses_…/capture

→ 200 OK
{
  "kind": "screenshot",
  "data": "<base64-encoded bytes>",
  "encoding": "base64",
  "byte_size": 184320,
  "duration_ms": 412
}

Captures return inline base64 bytes — there is no presigned URL. Decode data on the client according to encoding. For long-running session recordings (a separate artifact), see /docs/recordings.

Where to go next

• Full API reference — every endpoint, every field.
• Cost monitoring — how to keep your bill predictable.
• OAuth apps — for third-party integrations acting on a customer's behalf.
• Pricing — tier comparison + crypto payment option.

Need help?

[email protected]. We respond within one business day.