Run a device action Beta

Run one capability on one device

Beta. This endpoint is live for design partners, with keys that Dopl issues while the developer portal is being built.

POST /v1/devices/{device_id}/actions/{capability}

The device must be online, publish the capability and allow it under its profile, and the user's grant must cover it. ask.* actions hold up to 200 seconds for the answer, unless you send Prefer: respond-async. T4 capabilities fail with confirmation_denied by default; when the profile sets a confirmation mode they return needs_confirmation and do not run. Secret key, scope actions:write.

Authorizations

Authorizationrequiredheaderstring

A project secret key (sk_test_… or sk_live_…) sent as Authorization: Bearer <key>. Server to server only.

Idempotency-Keyheaderstring

Optional. When sent it must equal the body's idempotency_key, or the request fails with invalid_request. A retry with the same key and body returns the first response; the same key with a different body returns idempotency_conflict.

Preferheaderstring

respond-async (RFC 7240): do not hold an ask for its answer. The 202 returns at once with status queued or delivered; read the answer with GET /actions/{id} or the action.completed webhook. Other preferences are ignored.

Path parameters

device_idrequiredpathstring

The device to act on.

capabilityrequiredpathstring

A capability ID such as present.display, present.notify or ask.choice.

Body

argsrequiredobject

The capability's arguments, such as { "body": "…" } for present.notify.

idempotency_keyrequiredstring

1 to 255 characters, unique per request within the environment. The TypeScript SDK fills one when you pass none.

StatusBody
202DeviceActionResponse
400, 401, 403, 404, 409, 422, 429, 502Error