Beta. The Device SDK is live for design partners: Dopl issues your project's keys while the developer portal is being built, and @dopl/sdk is available on request. Agents that act for one signed in Dopl user can use the hosted MCP server instead.
@dopl/sdk is a typed client for every route in the API reference, with request and response types taken from the same contract. It runs on Node 18.17 or later and anywhere with a global fetch.
Access
The package is private while the Device SDK is in testing and is not on npm. It is available to design partners on request from sales@usedopl.com, and the Quickstart walks through it end to end.
Create a client
import { Dopl } from "@dopl/sdk";
const dopl = new Dopl({ apiKey: process.env.DOPL_SECRET_KEY! });new Dopl({ apiKey, baseUrl, fetch, headers }) takes a secret key, or a publishable pk_ key that can only call connectSessions.create; the client refuses every other call with a pk_ key before sending anything. The key is never logged or kept as a property on the client.
Methods
| Method | Route |
|---|---|
connectSessions.create(body) | POST /connect_sessions |
connections.exchange({ public_token }) | POST /connections/exchange |
connections.list(externalUserId) | GET /users/{external_user_id}/connections |
connections.revoke(connectionId) | DELETE /connections/{id} |
users.context(externalUserId) | GET /users/{external_user_id}/context |
users.deliver(externalUserId, body) | POST /users/{external_user_id}/deliver |
devices.action(deviceId, capability, args) | POST /devices/{device_id}/actions/{capability} |
devices.get(deviceId) | GET /devices/{id} |
actions.get(actionId) | GET /actions/{id} |
events.list({ cursor, limit, ...filters }) | GET /events |
webhookEndpoints.create({ url, enabled_events }) | POST /webhook_endpoints |
webhookEndpoints.list({ cursor, limit }) | GET /webhook_endpoints |
webhookEndpoints.get(endpointId) | GET /webhook_endpoints/{id} |
webhookEndpoints.update(endpointId, body) | PATCH /webhook_endpoints/{id} |
webhookEndpoints.delete(endpointId) | DELETE /webhook_endpoints/{id} |
webhookEndpoints.rotateSecret(endpointId, { overlap_seconds }) | POST /webhook_endpoints/{id}/rotate_secret |
webhookEndpoints.listDeliveries(endpointId, { cursor, limit }) | GET /webhook_endpoints/{id}/deliveries |
webhookDeliveries.get(deliveryId) | GET /webhook_deliveries/{id} |
webhookDeliveries.replay(deliveryId) | POST /webhook_deliveries/{id}/replay |
show(externalUserId, { text, blocks }) | Deliver with the display intent |
notify(externalUserId, { text }) | Deliver with the notify intent |
ask(externalUserId, { question, options }) | Deliver with the ask intent, then poll the action for the answer |
show, notify and ask are methods, not routes, so the API keeps one way to deliver. Each takes the Deliver options too: urgency, target, profile and idempotencyKey.
Asking
const answer = await dopl.ask("usr_123", { question: "Ship it?", options: ["Yes", "No"], timeoutMs: 60_000 });
if (answer.status === "answered") console.log(answer.answer);ask delivers the question, then polls actions.get with the delivery_id every second until the action is done or fails, or until timeoutMs passes, 200 seconds by default. An answer resolves with status: "answered", a timeout resolves with status: "timeout", and a failed action throws.
Idempotency
Every POST takes { idempotencyKey }, which the SDK sends as the Idempotency-Key header and in the body. When you pass none it creates a fresh key per call, so pass your own to make a retry safe: the same key returns the first result instead of acting twice.
Errors
Every failure throws a DoplError with the fields of the error shape (code, type, message, retryable, docUrl, deviceKind) plus the HTTP status and the requestId from the Request-Id header. When no error body came back, code is one the SDK sets itself: network_error, unexpected_response or publishable_key_not_allowed.
import { DoplError } from "@dopl/sdk";
try {
await dopl.notify("usr_123", { text: "Build done" });
} catch (err) {
if (err instanceof DoplError && err.retryable) {
// retry later with the same idempotencyKey
}
}A Python SDK is planned after TypeScript.