Workforce Agents API
Drive a single agent over HTTP. Every request is authenticated with that agent's API key, sent as a bearer token:
All endpoints are scoped to one agent through the {agentId} path segment - find the agent ID in the agent's page URL in the dashboard. A key only works for the agent it was created for.
Start a thread
Dispatch a message to the agent. This starts a new thread and returns immediately.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | The task or message for the agent |
files | FileReference[] | No | Hosted file attachments |
Response
Returns 201.
Poll the Get a thread endpoint until the status is terminal.
Example
Get a thread
Read a thread's status and messages. Poll this until the run finishes.
Response
| Field | Type | Description |
|---|---|---|
threadId | string | The thread identifier |
status | string | idle, queued, pending, running, completed, failed, or cancelled |
failureReason | string | null | Why the run failed, when status is failed |
messages | UIMessage[] | The conversation - see UIMessage parts |
Keep polling while the status is pending, queued, or running. Stop when it is completed, failed, or cancelled.
Example
Follow up in a thread
Send another message into an existing thread. If the agent is still working the message runs after the current turn finishes; otherwise it starts immediately.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | The follow-up message |
files | FileReference[] | No | Hosted file attachments |
Response
Returns 202.
Poll Get a thread for the new run's result.
Example
Errors
Errors return { "error": string, "code": string } with an HTTP status:
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
402 | The agent is blocked by a usage or spending limit |
403 | The key is not authorized for this agent |
404 | The thread does not exist for this agent |