# 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."}'
```

## Handling the response from the worker

The agent will stream its response as [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.

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.

## Continuing an interaction with an agent

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 finds pro
curl -XPOST https://agents.toolhouse.ai/$AGENT_ID \
  -v -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ 
# 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.