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.

Calling your worker

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

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. 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.

# 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 (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:

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

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.

Recommended polling flow

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

# 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.