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


---

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