> For the complete documentation index, see [llms.txt](https://docs.toolhouse.ai/toolhouse/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolhouse.ai/toolhouse/developers/workers-api.md).

# Workers API

## Workers API

Each worker can be called as an API. The API endpoint is formatted as `https://agents.toolhouse.ai/$AGENT_ID`, where `$AGENT_ID` is a unique GUID assigned to your worker. You must authenticate your request with your API Key.

You can create an API Key in the [API Keys page](https://toolhouse.app/settings/api-keys).

### Calling your worker

You can call your worker by simply making a `POST` request towards its endpoint.

```bash
curl -XPOST \
  https://agents.toolhouse.ai/$AGENT_ID \
  -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY'
  --json '{"message": "Book at meeting over lunch with Jessica."}'
```

The response headers will contain a `X-Toolhouse-Run-ID` header containing a unique ID for the execution run. You can use this value to continue the interaction with your worker. You can think of this ID as an identifier of the current context including the initial message, any tool call, and the response from the worker.

### Handling the response from the worker

The agent can stream its response as text or [NDJSON](https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON). You will be able to see both the agent's output and the tool calls.

**Text endpoints**

Text response endpoints will only include the worker's output. They will not output tool calls or debug information. We offer these endpoints as a convenience, so you won't have to build additional logic to parse the worker's response when you only need to see its user-facing output.

The following text endpoints are available:

* POST `https://agents.toolhouse.ai/$AGENT_ID`: start a new worker task
* PUT `https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID`: continue an interaction with a worker

**NDJSON endpoints**

NDJSON endpoints will output the worker's output and out-of-band signals such as tool calls and their responses. These endpoints are useful if you need to display or debug tool calls from your agent.

The following NDJSON endpoints are available:

* POST `https://agents.toolhouse.ai/ndjson/$AGENT_ID`: start a new worker task
* PUT `https://agents.toolhouse.ai/ndjson/$AGENT_ID/$RUN_ID`: continue an interaction with a worker

### Continuing an interaction with a worker

The `X-Toolhouse-Run-ID` header returned in the initial response from the POST call will allow you to continue the interaction with this worker while keeping a reference of the current context. Using a Run ID is particularly useful for conversational workers, because it allows them to retain all the content and history from previous messages.

To continue a conversation, you can use the Run ID in a `PUT` request to the same agent endpoint.

```bash
# Initial request to execute the worker, assuming $AGENT_ID is a deal finder
curl -XPOST https://agents.toolhouse.ai/$AGENT_ID \
  -v -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ 
  --json '{
  "message": "Find discounts on wide-angle computer displays"
}'
# Headers will contain x-toolhouse-run-id: $RUN_ID
# Worker will stream the response

# Continuing the conversation using the X-Toolhouse-Run-ID
curl -XPUT https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \
-H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
--json '{
  "message": "thank you, now find products similar to an iPhone"
}'
# Headers will contain x-toolhouse-run-id: $RUN_ID
# Agent will stream a new response using the current context
```

The `PUT` request will also send a `X-Toolhouse-Run-ID` header containing the run ID for subsequent requests.

***

### Background execution with Virtual Computer (Code Interpreter)

Workers that use [Virtual Computer](https://docs.toolhouse.ai/toolhouse/capabilites/virtual-computer) (also known as Code Interpreter) may execute jobs in the background. When this happens, the API signals the background execution via response headers, and your client is expected to poll until the job completes before resuming the conversation.

#### How background execution works

When a tool such as `code_interpreter` requests background execution, the Workers API:

1. Returns a `x-toolhouse-job-id` header on the relevant endpoints to signal that a job is running.
2. Blocks new `PUT` requests (returning `409`) until the job completes.
3. Allows new `POST` requests to start fresh interactions as normal.
4. Expects your client to poll the `GET` endpoint and resume with a `PUT` once the header disappears.

#### Endpoint behavior during background execution

**GET `/:agent_id/:run_id`**

Poll this endpoint to check whether a background job is still running.

While a job is in progress, the response includes:

```
x-toolhouse-job-id: $JOB_ID
```

Once the job completes (successfully or with an error), the header is absent. The absence of this header is your signal that the agent is ready to receive a new message.

**PUT `/:agent_id/:run_id`**

Sending a `PUT` while a job is in progress returns:

```
HTTP 409 Conflict
```

The request is rejected until background execution completes. Your code must poll the `GET` endpoint to check for the completion of this execution.

Once the `GET` endpoint no longer returns `x-toolhouse-job-id`, send a `PUT` with any `message` value to resume inference:

```bash
curl -XPUT https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \
  -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
  --json '{"message": "continue"}'
```

{% hint style="info" %}
If the agent itself decides to call Code Interpreter again in response to your `PUT`, the same background execution flow restarts. Check for `x-toolhouse-job-id` in the `PUT` response headers and resume polling the `GET` endpoint as needed.
{% endhint %}

#### Recommended polling flow

```mermaid
flowchart TD
    A([POST /:agent_id]) --> B[Receive x-toolhouse-run-id]
    B --> C{Response contains\nx-toolhouse-job-id?}
    C -- No --> G[Handle streamed response]
    C -- Yes --> D[GET /:agent_id/:run_id]
    D --> E{x-toolhouse-job-id\npresent?}
    E -- Yes, wait --> D
    E -- No, break --> F["PUT /:agent_id/:run_id {'message': ''}"]
    F --> H{x-toolhouse-job-id\nin response?}
    H -- Yes --> D
    H -- No --> G
```

```
POST /:agent_id
  └─► Receive x-toolhouse-run-id: $RUN_ID

  If response contains x-toolhouse-job-id:
    Loop:
      GET /:agent_id/$RUN_ID
        If x-toolhouse-job-id present → wait, then repeat
        If x-toolhouse-job-id absent  → break

    PUT /:agent_id/$RUN_ID  {"message": ""}
      └─► If x-toolhouse-job-id present → repeat polling loop
          If no job header             → handle streamed response
```

#### Example: polling until a Code Interpreter job completes

```bash
# Start the task
RUN_ID=$(curl -sI -XPOST https://agents.toolhouse.ai/$AGENT_ID \
  -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
  --json '{"message": "Analyze this CSV and plot a histogram"}' \
  | grep -i x-toolhouse-run-id | awk '{print $2}' | tr -d '\r')

# Poll until the background job finishes
while true; do
  JOB_ID=$(curl -sI https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \
    -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
    | grep -i x-toolhouse-job-id | awk '{print $2}' | tr -d '\r')

  if [ -z "$JOB_ID" ]; then
    echo "Job complete, resuming..."
    break
  fi

  echo "Job $JOB_ID in progress, waiting..."
  sleep 3
done

# Resume inference
curl -XPUT https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \
  -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
  --json '{"message": ""}'
```

#### Frontend / widget integration

If you are building a UI on top of the Workers API, you can use the `x-toolhouse-job-id` header from the `GET` endpoint to:

* Show a loading or progress indicator while the job runs.
* Disable the message input field until the header disappears.
* Resume the conversation automatically by sending a `PUT` once polling succeeds.

***

### Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolhouse.ai/toolhouse/developers/workers-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolhouse.ai/toolhouse/developers/workers-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.