Profiles

A profile is a reusable, named handle to a stable browser identity (archetype + persisted browser state). The control-plane stores only the metadata you see in the /v1/profiles responses; per-profile cookies, localStorage, and IndexedDB live in the WebKit driver layer. Snapshot them with POST /v1/profiles/:id/snapshots and restore later via POST /v1/profile-snapshots/:id/restore.

When to use a profile

Authenticated scraping. The site requires login; you want each session to carry over cookies + storage without re-authenticating.
A/B-tested rendering. The site personalises based on cookies; you want each run to see the same variant.
Archetype pinning. You want to lock the browser fingerprint (UA / viewport / timezone / locale) to a specific Driftstack-managed archetype slug across runs.

If your automation doesn't care about identity continuity, skip profiles and let sessions run with the account's default archetype.

POST /v1/profiles — mint

POST /v1/profiles
Authorization: Bearer ds_live_…
Content-Type: application/json

{
  "name": "us-east-sales-bot",
  "archetype": "iphone17_ios18_7_safari26_4",   ← optional, defaults server-side
  "description": "Sales-team account for east-coast scraping.",
  "folder": "Sales",                            ← optional, ≤32 chars
  "tags": ["us-east", "scraping"],              ← optional, ≤12 unique, ≤24 chars each
  "icon": "🛒",                                  ← optional, short emoji (synced per-account)
  "note": "warmed up"                           ← optional, ≤280 chars
}

→ 201 Created
{
  "id": "prof_…",
  "name": "us-east-sales-bot",
  "archetype": "iphone17_ios18_7_safari26_4",
  "description": "Sales-team account for east-coast scraping.",
  "folder": "Sales",
  "tags": ["us-east", "scraping"],
  "icon": "🛒",
  "note": "warmed up — ready for checkout flows",
  "last_used_at": "2026-05-11T12:00:00.000Z",
  "size_bytes": 12900000,
  "last_saved_at": "2026-05-11T12:00:00.000Z",
  "created_at": "2026-05-01T00:00:00.000Z",
  "updated_at": "2026-05-11T12:00:00.000Z",
  "deleted_at": null
}

The response is a flat profile object — no envelope. Profile ids are prefixed prof_. The archetype field is a lowercase slug (1–120 chars) identifying a Driftstack-managed device profile; the server applies the account's locked archetype if you omit it. Browser state (cookies, localStorage, etc.) is created on first use and is not part of the create request.

size_bytes is the byte size of the profile's saved browser-state store, and last_saved_at is when it was last written back — both null until the profile is first used and saved. Use them to surface per-profile and account-wide storage usage.

GET /v1/profiles — list

GET /v1/profiles?limit=25
Authorization: Bearer ds_live_…

→ 200 OK
{
  "data": [ /* Profile objects */ ],
  "has_more": true,
  "next_cursor": "eyJ0aWQiOi…"   ← null when no more pages
}

Cursor pagination. Default page size 50; max 100. Pass the previous response's next_cursor as ?cursor= on the next request.

GET /v1/profiles/:id

GET /v1/profiles/prof_…
Authorization: Bearer ds_live_…

→ 200 OK
{
  "id": "prof_…",
  "name": "us-east-sales-bot",
  "archetype": "iphone17_ios18_7_safari26_4",
  "description": "Sales-team account for east-coast scraping.",
  "folder": "Sales",
  "tags": ["us-east", "scraping"],
  "icon": "🛒",
  "note": "warmed up — ready for checkout flows",
  "last_used_at": "2026-05-11T12:00:00.000Z",
  "size_bytes": 12900000,
  "last_saved_at": "2026-05-11T12:00:00.000Z",
  "created_at": "2026-05-01T00:00:00.000Z",
  "updated_at": "2026-05-11T12:00:00.000Z",
  "deleted_at": null
}

PATCH /v1/profiles/:id — update

PATCH /v1/profiles/prof_…
Authorization: Bearer ds_live_…
Content-Type: application/json

{
  "name": "us-east-sales-bot-v2",
  "description": "Renamed after the 2026-05 reorg.",
  "folder": null,
  "tags": ["us-east", "scraping", "v2"]
}

→ 200 OK
{
  "id": "prof_…",
  "name": "us-east-sales-bot",
  "archetype": "iphone17_ios18_7_safari26_4",
  "description": "Sales-team account for east-coast scraping.",
  "folder": "Sales",
  "tags": ["us-east", "scraping"],
  "icon": "🛒",
  "note": "warmed up — ready for checkout flows",
  "last_used_at": "2026-05-11T12:00:00.000Z",
  "size_bytes": 12900000,
  "last_saved_at": "2026-05-11T12:00:00.000Z",
  "created_at": "2026-05-01T00:00:00.000Z",
  "updated_at": "2026-05-11T12:00:00.000Z",
  "deleted_at": null
}

name, description, folder and tags are patchable — folder: null files the profile back under no folder, and tags is an exact-set replace ([] clears them). To change the archetype, clone the profile via POST /v1/profiles/:id/clone and discard the old one (the archetype is set at create time and pins the device identity for the life of the profile).

DELETE /v1/profiles/:id

DELETE /v1/profiles/prof_…
Authorization: Bearer ds_live_…

→ 204 No Content

The profile + its persisted browser state are removed. In-flight sessions that started with this profile keep running but can't be pinned to it again. Idempotent: a second DELETE on the same id returns 204.

Snapshots

Profile snapshots are immutable point-in-time copies of the profile + its browser state. Customers can restore a snapshot into a fresh profile if the current state is broken (e.g. the site logged the profile out):

# Capture
POST /v1/profiles/prof_…/snapshots
Authorization: Bearer ds_live_…
Content-Type: application/json

{ "label": "before-2026-05-12-relogin", "description": "Last-known-good." }

→ 201 Created
{
  "id": "psnap_…",
  "parent_profile_id": "prof_…",
  "label": "before-2026-05-12-relogin",
  "description": "Last-known-good.",
  "parent_archetype": "iphone17_ios18_7_safari26_4",
  "parent_name": "us-east-sales-bot",
  "captured_at": "2026-05-12T12:00:00.000Z",
  "created_at": "2026-05-12T12:00:00.000Z"
}

# List per profile (cursor-paginated; same shape as /v1/profiles)
GET /v1/profiles/prof_…/snapshots

# Restore into a NEW profile (the source snapshot is immutable)
POST /v1/profile-snapshots/psnap_…/restore
Authorization: Bearer ds_live_…
Content-Type: application/json

{ "name": "us-east-sales-bot-restored" }

→ 200 OK   ← returns the newly minted profile object

Snapshot ids are prefixed psnap_. The restore endpoint lives under /v1/profile-snapshots, not under /v1/profiles/<parent>/snapshots. Each restore creates a fresh profile; the snapshot itself is immutable.

Privacy + retention

Cookies + storage state are stored in encrypted form at rest in the driver layer.
Profile metadata + snapshot rows are deleted on account deletion + per the documented retention policy.
No identifying customer data is embedded in the profile record — the only customer-supplied fields are name and description.

Limits

Profile cap by tier (per PROFILES_PER_TIER):

Tier	Profile cap
Free	1
Personal	10
Team	50
Agency	200
API Starter	25
API Builder	100
API Scale	500
Enterprise	custom

Need more? Email support.

Support

[email protected].