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
AuthorizationA project secret key (sk_test_… or sk_live_…) sent as Authorization: Bearer <key>. Server to server only.
Idempotency-KeyOptional. 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.
Preferrespond-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_idThe device to act on.
capabilityA capability ID such as present.display, present.notify or ask.choice.
Body
argsThe capability's arguments, such as { "body": "…" } for present.notify.
idempotency_key1 to 255 characters, unique per request within the environment. The TypeScript SDK fills one when you pass none.
| Status | Body |
|---|---|
202 | DeviceActionResponse |
400, 401, 403, 404, 409, 422, 429, 502 | Error |