Local reference

Distributed workers

List Workers

Everything the workers panel renders, in one call.

Response Body

`application/json`

bash

curl -X GET "https://example.com/workers"

json

{}

Get Target

What the GPU picker shows: the choice, the resolved answer, the options.

active is the same answer the generation path uses, so the badge cannot claim work goes somewhere the router will not send it. Pass op for the surface being rendered — omitting it answers for the target as a whole, which is what the picker's own menu asks.

Query Parameters

op?Op

Default""

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/workers/target"

json

{}

Set Target

Choose where work runs. Exactly one target is active at a time.

Request Body

application/json

local, or the id of an enrolled worker.

target*Target

Lengthlength <= 64

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/target" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "string"
  }'

json

{}

Set Enabled

Turn the feature on or off.

Off means off: the control plane stops, the listening socket closes, and the app is exactly what it was before the toggle existed.

Request Body

application/json

enabled*Enabled

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/enabled" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

json

{}

Agent Status

The other side of the same feature: is THIS machine lending its GPU?

Separate from GET /workers, which answers for the control plane. A machine can legitimately be both — a desktop that borrows a laptop's GPU and lends its own to a colleague — so neither status can stand in for the other.

Response Body

`application/json`

bash

curl -X GET "https://example.com/workers/agent"

json

{}

Join Control Plane

Redeem a join code and start working for that control plane.

This is the endpoint that makes the feature reachable. Joining used to mean setting OMNIVOICE_WORKER_MODE and OMNIVOICE_WORKER_TOKEN in the environment and relaunching the app — a step most users will never take, on the machine that is usually the least convenient to configure by hand.

The code is single-use and short-lived, so a failure here is nearly always "expired" or "wrong address"; it is returned verbatim rather than as a bare 409, because the user's next action depends on which one it was.

Request Body

application/json

A join code, as pasted (or scanned) from the control plane.

token*Token

Lengthlength <= 4096

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/agent/join" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

json

{}

Set Agent Enabled

Start or stop lending this machine, without forgetting the enrollment.

Off stops the agent and clears the setting, so nothing dials out; the pinned certificate stays, which is what lets "on" resume without asking for another code.

Request Body

application/json

enabled*Enabled

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/agent/enabled" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

json

{}

Create Enrollment

Mint a single-use join token.

The plaintext is returned once and never stored — the response is the only time it exists outside the worker that redeems it.

Request Body

application/json

label?Label

Lengthlength <= 120

Default""

endpoint?Endpoint

Lengthlength <= 256

Default""

ttl_seconds?Ttl Seconds

Range60 <= value <= 86400

Default900

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/enrollments" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{}

Update Worker

Path Parameters

worker_id*Worker Id

Request Body

application/json

name?|null

enabled?boolean|null

priority?|null

Response Body

`application/json`

`application/json`

bash

curl -X PATCH "https://example.com/workers/string" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{}

Revoke Worker

Remove a worker — which means revoke its key, not hide the row.

Its in-flight work is released so it can be retried elsewhere rather than waiting out a lease on a machine that will never answer again.

Path Parameters

worker_id*Worker Id

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/workers/string"

json

{}

Record the user's explicit yes to sending their audio to this machine.

Path Parameters

worker_id*Worker Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/string/consent"

json

{}

Clear Breaker

Clear a paused worker's circuit breakers.

The user fixed the machine and knows it — a breaker with no manual clear is the quarantine trap the reputation system had.

Path Parameters

worker_id*Worker Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/string/resume"

json

{}

List Tasks

Recent remote tasks, for the queue view.

Query Parameters

limit?Limit

Default50

Response Body

`application/json`

`application/json`

bash

curl -X GET "https://example.com/workers/tasks"

json

{}

Submit Task

Run one task on a remote worker and wait for it. DEV ONLY.

This is the producer the remote pipeline never had: until it existed the scheduler had no caller outside the test suite, so picking a remote GPU changed the badge and nothing else — every job still ran locally. It is the smallest thing that makes remote execution observable end to end, not the shipping surface: the GPU gateway takes over routing real generation and this endpoint goes with it.

Loopback-only and behind the same opt-in as the rest of the feature, so a user who never enabled remote workers cannot reach it at all.

Request Body

application/json

One unit of work for a remote worker. Dev only — see submit_task.

engine*Engine

Lengthlength <= 64

operation?Operation

Lengthlength <= 32

Default"tts"

model_id?Model Id

Lengthlength <= 128

Default""

params?

deadline_seconds*Deadline Seconds

Range0 < value <= 21600

idempotency_key?|null

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "string",
    "deadline_seconds": 1
  }'

json

{}

Cancel Task

Path Parameters

task_id*Task Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/tasks/string/cancel"

json

{}

Inbound Status

Response Body

`application/json`

bash

curl -X GET "https://example.com/workers/inbound"

json

{}

Set Inbound Enabled

Request Body

application/json

enabled*Enabled

bind?Bind

Default""

port?Port

Default0

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/inbound/enabled" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

json

{}

Issue Inbound Key

Mint one panel's key and return the string it pastes.

The secret is in this response and nowhere else afterwards — only its hash is stored, so it cannot be shown again, only replaced.

Request Body

application/json

label?Label

Lengthlength <= 64

Default""

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/inbound/keys" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{}

Revoke Inbound Key

Revoke one panel. Everyone else stays connected — the whole reason keys are per panel rather than one shared node key.

Path Parameters

key_id*Key Id

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/workers/inbound/keys/string"

json

{}

Disconnect Inbound Session

Path Parameters

session_id*Session Id

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/inbound/sessions/string/disconnect"

json

{}

Add Inbound Connection

Paste a connection string from a GPU machine and dial it.

Request Body

application/json

connection_string*Connection String

Length1 <= length <= 512

Response Body

`application/json`

`application/json`

bash

curl -X POST "https://example.com/workers/inbound/connections" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_string": "string"
  }'

json

{}

Remove Inbound Connection

Path Parameters

endpoint*Endpoint

Response Body

`application/json`

`application/json`

bash

curl -X DELETE "https://example.com/workers/inbound/connections/string"

json

{}

Sessions

Previous Page

Overview

Preview of the versioned VoiceStudio Cloud public developer contract.