Wework API Client

Operate Wework conversations over HTTP, including standalone chats, project-directory tasks, and worktree tasks. The API Client shares Wework's device Runtime conversations, message dispatch, and execution state. It adds no database tables or duplicate conversation storage.

Authentication and base URL

Create a personal API key in Wegent and send:

Authorization: Bearer wg-...

The base path is /api/v1, shared with the existing Wegent Responses endpoint. Reverse proxies must forward this prefix to Backend and disable SSE buffering. Expired/revoked keys and inactive users receive 401 on subsequent requests. Login JWTs and service keys are not accepted.

Existing Wegent API compatibility

Existing requests remain unchanged: model: "namespace#team_name" without execution uses the original agent pipeline, tools, authentication, and numeric response IDs. New Wework conversations explicitly use execution: {"type": "wework", "device_id": "..."}, with model selected from the Wework model catalog.

Wework accepts personal keys through X-API-Key or Authorization: Bearer. Conversation and model discovery currently serve Wework data and accept execution=wework; other values are rejected. Conversations can be filtered by device_id. Existing /api/tasks, /api/models, and other endpoints stay unchanged. Existing DELETE response behavior is preserved; Wework deletion is unsupported.

Set the OpenAI SDK base_url to https://example.com/api/v1 and pass the target through extra_body={"execution": {"type": "wework", "device_id": "..."}}. Pass model, input, stream, and background normally. Wework supports the text subset; agent tools, attachments, and generation options are rejected with 422.

Endpoints

Method and path (relative to the base path)	Purpose
GET /devices	Current user devices, including offline devices
GET /conversations?limit=20&after=...	Conversations on online devices, including project workspace tasks
GET /conversations/{id}?limit=20&before=...	Paginated transcript and latest_response
POST /responses	Create or continue a conversation
GET /responses/{id}	Read one turn's current status and output from Runtime
GET /responses/{id}?stream=true	Subscribe to new output for that turn
POST /responses/{id}/cancel	Request cancellation of that turn
GET /models	Models available to the caller for Codex conversations

Each user message defines a response turn. A response ID encodes its Runtime address and native user-message identity; no Backend lookup table is required. IDs grant no permissions. Every read, continuation, and cancellation checks the caller's accessible devices and conversations.

PC/mobile conversations are accessible too. Use latest_response.id from conversation details to inspect, subscribe to, or cancel their latest turn. is_latest identifies the last user turn; status describes that turn's execution state.

Current session information available to the model

Every turn in a Codex conversation started from desktop, mobile, or the API receives wework.session.current through additionalContext. The model can read these values without asking the user to copy IDs:

Field	Meaning
base_url	HTTP API address including /api/v1; null when no backend is configured
api_conversation_supported	Whether the conversation supports the API; Codex standalone, project-directory, and worktree tasks are supported; does not indicate connectivity or authorization
conversation_id	Current conv_... ID for conversation queries and follow-ups
response_id	Current user turn's resp_... ID for querying, streaming, and cancellation
execution	type: "wework" and the current device_id for new requests
model	Full cloud model API ID, such as public:default:0:my-model
model_name, model_type	Selected model name and source

These are HTTP API routing IDs, distinct from native Codex thread/turn IDs. A conversation ID encodes the device ID and Runtime-local task ID; project-directory and worktree tasks can use these IDs directly for retrieval and continuation. Follow-ups retain the conversation ID, receive a new response ID, and refresh the selected model information. Local models and selections without cloud catalog identity have model: null; choose an available model from GET /models?execution=wework for HTTP requests.

Each turn includes only these fields and brief usage guidance; full API instructions remain in this document to avoid repeating them in the context. Wait for the current turn to finish before continuing it, use either conversation or previous_response_id, and omit device and title. No personal API Keys, login tokens, or model secrets are injected; HTTP calls still require a separately supplied personal API Key.

Create a task

Call /devices to select a device, then /models to get a model id. The device list uses the same personal API key and returns:

{
  "object": "list",
  "data": [
    {
      "device_id": "your-device-id",
      "name": "My Wework",
      "status": "online",
      "device_type": "local",
      "is_default": true
    }
  ]
}

status is online, offline, or busy; data is empty when no devices exist. Pass the selected device_id as execution.device_id for a new conversation. is_default is informational and does not select a device automatically. Online status does not guarantee task acceptance; execution still validates remote control permission and Runtime capabilities.

curl -N 'https://example.com/api/v1/responses' \
  -H "Authorization: Bearer $WEGENT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "public:default:0:my-model",
    "input": "Inspect the workspace and explain the project",
    "stream": true,
    "execution": {
      "type": "wework",
      "device_id": "your-device-id",
      "title": "API conversation"
    }
  }'

• stream: true: Responses SSE events, including response.created, response.output_text.delta, and a terminal event.
• background: true, stream: false: return a response ID after Runtime accepts the submission; retrieve the result with GET.
• Both false: wait for the turn to finish and return its response object.
• input accepts text or an array of user text messages with input_text content blocks.
• Creation and continuation currently use Codex Runtime. Runtime owns tool configuration. Client-defined function tools, tool-output submission, and injected assistant history are not supported.
• execution.model_type can disambiguate model sources; prefer the full ID from /models. model_options passes existing Runtime model options. Resource identity always comes from the authorized server catalog.

The backend Model configuration determines each cloud model's upstream protocol; model_options cannot override it. Runtime converts requests and streaming responses for OpenAI Responses, Chat Completions, or Anthropic Messages while the public API consistently uses Responses. Provider API keys remain on the backend.

Continue with conversation, omitting device and title:

{
  "model": "public:default:0:my-model",
  "conversation": "conv_...",
  "input": "Now check test coverage",
  "background": true
}

Alternatively, supply previous_response_id. It must identify the latest finished turn; historical branching is unsupported. A running conversation returns 409; wait for it or request cancellation first.

GET /models uses the same cloud catalog, permissions, and availability filters as the Wework desktop. Native Codex Shell protocol restrictions do not exclude gateway-backed models. Device-local catalogs such as “My CodeX” are separate from this cloud list. Use the exact returned model id, formatted as type:namespace:resourceUserId:name, such as public:default:0:my-model.

Status, streaming, and cancellation

Statuses include queued, in_progress, completed, failed, cancelled, and incomplete. GET builds a snapshot from native history; model information reflects the Runtime's current conversation configuration.

Subscribing to a running response starts with new events from the time of subscription. Its response.created.output is empty; use ordinary GET for existing content. Streaming a completed response returns its snapshot and terminal event. sequence_number is connection-local; starting_after and historical event replay are unsupported.

Disconnecting SSE does not cancel execution. cancellation_requested: true means Runtime accepted the cancellation request; use GET for the eventual execution state. Cancelling a finished older turn cannot stop a newer task. If native turn identity is insufficient for safe cancellation, the API returns 409.

The owning device must be online and allow remote control. Offline device conversations cannot be read or executed. An RPC submission timeout does not prove that execution did not start: use the error's response_id and conversation_id to inspect the result before resubmitting.

Continuation calls runtime.tasks.get by ID to retrieve the original workspace, Team binding, and model options, then reuses Wework execution configuration compilation and runtime.tasks.send. It does not list tasks or scan other workspaces. Validation of previous_response_id reuses the same task lookup. Explicit model options override the original options while retaining the task's workspace and binding.

Update backend and Executor together to versions supporting runtime.tasks.get. Older Executors return an explicit unsupported RPC error; there is no fallback to listing all tasks.

Offline devices return 503 device_offline; missing or inaccessible devices return 404 device_not_found; missing tasks on an online device return 404 task_not_found; Runtime lookup failures return 502. A missing task is not reported as an offline device.

Architecture

Redis only forwards live events; it stores no keys, event journal, or response state. Runtime owns asynchronous execution; Backend does not introduce a separate task executor.

Device-specific operations validate ownership and the online route before RPC. Offline devices return HTTP 503 with detail.code: device_offline; missing or inaccessible devices return 404. Individual conversation/response lookups query only the target device. A connection loss not yet detected by heartbeats may still require an RPC timeout.