HTTP API

The same operations as the MCP tools, over plain HTTPS and JSON. The API is in preview, so expect additions.

Base URL: https://api.distilled.cx
Auth: Authorization: Bearer dk_live_a1b2c3d4e5f6g7h8_<secret>

Authentication

Every call needs an API key. A key carries scopes, and each endpoint lists the scope it needs. Check a key with:

curl https://api.distilled.cx/v1/me -H "Authorization: Bearer $DISTILLED_API_KEY"

Scopes

Scope	Grants
`phones:read`	List phones and read their state.
`phones:write`	Allocate phones onto the rack.
`apps:write`	Install an app on a phone.
`runs:read`	List and inspect runs, and read their events.
`runs:write`	Start and stop runs.
`skills:read`	List registered skills and cohorts.
`skills:write`	Create, change, and delete skills and cohorts.

Retries

Send an Idempotency-Key header on calls that change state to make retries safe. Reusing a key with a different body returns idempotency_conflict. On rate_limited, wait for the Retry-After header.

Endpoints

Account

GET`/v1/me`

Identify the workspace and scopes behind the key. Use it to check a key works.

Scope any · Returns workspace, and the key's id, name, scopes, and expiry

Phones

GET`/v1/phones`

Every phone in the workspace.

Scope phones:read · Returns phone[]

GET`/v1/phones/:id/apps`

Apps installed on a phone that a run can open. The catalogue is what you may install; this is what is there now.

Scope phones:read · Returns the phone id, its launchable packages, and when its node last measured them

POST`/v1/phones/allocate`

Claim phones from the warm pool, up to the workspace quota.

Scope phones:write · Returns phone[], or 409 capacity_unavailable when the pool is empty

Field	Type	Description
`count`	`integer`	How many phones to claim, 1 to 20. Default 1.
`device`	`string`	Device profile, such as pixel8pro.
`region`	`string`	Where the phone should run.

GET`/v1/phones/:id`

One phone by id.

Scope phones:read · Returns phone

Field	Type	Description
`id`required	`string`	Phone id.

POST`/v1/phones/:id/release`

Hand a phone back to the pool. It leaves the workspace at once and is wiped and re-identified before anyone can claim it again.

Scope phones:write · Returns { id, released: true }

Field	Type	Description
`id`required	`string`	Phone id.

Apps

GET`/v1/apps/search`

Search the app catalogue.

Scope phones:read · Returns app[]

Field	Type	Description
`q`required	`string`	Search text, as a query parameter.

GET`/v1/apps/:pkg`

One catalogue app by Android package name.

Scope phones:read · Returns app

Field	Type	Description
`pkg`required	`string`	Android package, such as com.example.app.

POST`/v1/apps/install`

Install a pinned app on chosen phones. Returns a run you can poll or stream.

Scope apps:write · Returns run

Field	Type	Description
`pkg`required	`string`	Android package to install.
`phones`	`string[]`	Phone ids to install on. Omit to target every phone in the workspace.

Skills

GET`/v1/skills`

Registered workflows.

Scope skills:read · Returns skill[]

POST`/v1/skills`

Scope skills:write · Returns skill

Field	Type	Description
`name`required	`string`	What the workflow is called.
`app`required	`string`	Android package the workflow drives.
`intent`	`string`	One sentence on what the workflow is for.
`workflow`required	`object[]`	The blocks to run: step, wait, repeat, or if.
`guardrails`	`object`	Time limit, stop conditions, and phone cap.
`risk`	`string`	low, medium, or high.
`targetCohort`	`string`	Cohort the workflow is meant for.

POST`/v1/skills/:id/enabled`

Enable or disable a registered workflow without deleting it.

Scope skills:write · Returns skill

Field	Type	Description
`id`required	`string`	Skill id.
`enabled`required	`boolean`	Whether runs may use it.

DELETE`/v1/skills/:id`

Delete a registered workflow.

Scope skills:write · Returns { deleted: true }

Field	Type	Description
`id`required	`string`	Skill id.

Cohorts

GET`/v1/cohorts`

Saved groups used to target runs.

Scope phones:read · Returns cohort[]

POST`/v1/cohorts`

Save a group of phones by region or device to target later.

Scope phones:write · Returns cohort

Field	Type	Description
`name`required	`string`	Unique within the workspace.
`filter`	`object`	Any of region (US or EU), model (device profile id), and app (Android package).

DELETE`/v1/cohorts/:id`

Delete a cohort.

Scope phones:write · Returns { deleted: true }

Field	Type	Description
`id`required	`string`	Cohort id.

GET`/v1/cohorts/:id/phones`

The phones a cohort currently matches.

Scope phones:read · Returns phone[]

Field	Type	Description
`id`required	`string`	Cohort id.

Runs

GET`/v1/runs`

Recent runs, newest first.

Scope runs:read · Returns run[]

POST`/v1/runs`

Start a run. It returns immediately; poll the run or stream its events.

Scope runs:write · Returns run

Field	Type	Description
`skill`required	`string \| object`	A registered skill id, or a workflow defined inline.
`target`	`string`	Cohort name. Omit to target every live phone.
`phones`	`string[]`	Phone ids, instead of a cohort.

GET`/v1/runs/:id`

One run, with its per-step state.

Scope runs:read · Returns run

Field	Type	Description
`id`required	`string`	Run id.

GET`/v1/runs/:id/events`

Server-sent events for a run. Resume with Last-Event-ID.

Scope runs:read · Returns text/event-stream of run events

Field	Type	Description
`id`required	`string`	Run id.

POST`/v1/runs/:id/stop`

Stop a run that is still going.

Scope runs:write · Returns run

Field	Type	Description
`id`required	`string`	Run id.

Errors

Failures return a JSON body with a stable code.

Code	Meaning
`invalid_request`	The body or a parameter failed validation.
`unauthorized`	The key is missing, malformed, revoked, or expired.
`insufficient_scope`	The key is valid but lacks the scope this call needs.
`not_invited`	The account is not a member of an active workspace.
`not_found`	No such resource in this workspace.
`idempotency_conflict`	The same Idempotency-Key was reused with a different body.
`capacity_unavailable`	No phone was free to claim.
`quota_exceeded`	The workspace is at its phone quota.
`rate_limited`	Too many calls. Retry after the Retry-After header.
`unavailable`	A dependency is down. Retrying is safe.

HTTP API

Authentication

Scopes

Retries

Endpoints

Account

GET/v1/me

Phones

GET/v1/phones

GET/v1/phones/:id/apps

POST/v1/phones/allocate

GET/v1/phones/:id

POST/v1/phones/:id/release

Apps

GET/v1/apps/search

GET/v1/apps/:pkg

POST/v1/apps/install

Skills

GET/v1/skills

POST/v1/skills

POST/v1/skills/:id/enabled

DELETE/v1/skills/:id