API reference
Explore authentication, device grants, action requests, custom functions and results in the shared openlaunch API.
The web console, MCP and device clients use the same command service and permission checks.
Authentication
Owner management uses an authenticated Clerk owner session. Google is the enabled sign-in provider; email/password sign-in is disabled. Agent MCP uses an admitted OAuth client, the correct resource audience, openlaunch:read, and separate capability grants. openlaunch:act permits action requests but does not create a device grant. OAuth uses PKCE.
Other agents and applications use an owner-created bridge SDK token. Choose read-only or action access and a lifetime of up to 30 days. The service still requires a separate grant for each device function. See Bridge SDK for setup and client examples.
Device requests use their own enrollment-issued bearer credential. On the hosted bridge they also include x-openlaunch-workspace, returned during pairing. Keep credentials out of logs and source control.
Routes
| Method | Route | Purpose |
|---|---|---|
| GET | /healthz |
Service health; not a device result |
| GET | /v1/devices |
Devices visible to the current principal |
| POST | /v1/enrollments |
Owner creates a 10-minute, single-use enrollment |
| GET | /v1/agent-connections |
Owner lists active SDK connections; secrets are omitted |
| POST | /v1/agent-connections |
Owner creates a named, expiring SDK token shown once |
| POST | /v1/agent-connections/{id}/revoke |
Owner revokes the connection and its grants |
| POST | /v1/device/{id}/manifest |
Device publishes implemented functions; changed manifests revoke grants |
| POST | /v1/device/enroll |
Device exchanges an enrollment for its credential |
| POST | /v1/grants |
Owner approves agent/device/capability access |
| POST | /v1/grants/revoke |
Owner revokes that agent’s access to a device |
| POST | /v1/devices/{id}/revoke |
Owner revokes the device credential |
| POST | /v1/devices/{id}/actions |
Request a supported capability |
| POST | /v1/broadcasts |
Request an action for up to 20 devices, with a result for each |
| GET | /v1/actions/{id} |
Inspect the command result |
| POST | /v1/actions/{id}/cancel |
Cancel an undispatched command |
| POST | /v1/device/{id}/next |
Device polls for its next command |
| POST | /v1/device/{id}/result |
Device reports success or failure |
| POST | /mcp |
Stateless device MCP requests |
Create an agent connection
An authenticated owner sends POST /v1/agent-connections with:
{ "name": "workbench agent", "access": "act", "ttlSeconds": 86400 }access is read or act; the token lifetime is 60–2,592,000 seconds. Save the returned token in protected storage when it is shown. Listing connections never returns the token again. A connection cannot enroll devices, approve itself or create another connection. Revocation removes its grants and cancels queued actions; it cannot undo an action already delivered.
Publish device functions
A device authenticates with its own credential and sends { "manifest": ... } to POST /v1/device/{id}/manifest. Its kind must match enrollment. Publishing an identical manifest keeps grants intact. A changed manifest removes previous device grants, cancels queued actions and marks outstanding received actions uncertain. The owner approves the functions again. Use the SDK’s publishManifest() or adapter CLI publish command rather than copying credentials into commands.
Request an action
{
"capability": "led.set",
"arguments": { "on": true },
"idempotencyKey": "your-unique-request-id",
"ttlSeconds": 60
}Built-in capabilities are device.health with {}, led.set with { "on": true }, and display.text with { "text": "hello" }. A device must advertise and implement the requested capability. Pi currently reports health; Uno implements all three.
TTL is 1–300 seconds. Reuse an idempotency key only for an identical request. A conflicting duplicate is rejected. Devices poll every 10 seconds, so allow enough time for delivery.
Custom device functions
A device can advertise custom functions in its manifest with a name, title, description and input schema. Schemas accept a root object with bounded string, number, integer or boolean fields. Additional root properties and external schema references are rejected. Each manifest supports up to 16 functions and each function up to 16 parameters; a custom function cannot replace a built-in capability.
The owner grants each custom function to an agent through the console. Granted functions appear as device-specific MCP tools. The service checks the current grant each time one is called, so a previously discovered tool stops working after its grant is revoked.
Broadcasts
POST /v1/broadcasts accepts up to 20 device IDs and a capability request, including its arguments, idempotency key and TTL. It returns an independent action or error for each device. A broadcast is not atomic: devices can accept, reject or complete the action independently. Inspect each action result.
Responses and errors
REST success responses use { "data": ... }. Errors use { "error": { "code": "...", "message": "..." } }; validation errors also identify invalid fields. HTTP 202 means accepted into the queue, not physically completed.
Inspect the returned action ID. queued and received are intermediate states. Terminal states distinguish success, failure, cancellation and expiry; an uncertain delivered outcome must not be reported as success. See pairing and permissions for the lifecycle.
Source
Protocol schemas, command service, HTTP adapter and MCP adapter live in the same repository. See resources for current source downloads and upstream tools.