# Run with API

Use the public agent invoke endpoint when you want to send a message to an agent from your own app or service. In Fetch Hive, you can copy the request shape from **More** -> **Get Code** in the agents sidebar or from **Code Snippet** in the agent editor.

## Authentication

```bash
Authorization: Bearer YOUR_API_KEY
```

See [API Keys](https://docs.fetchhive.com/your-workspace/api-keys) for how to create and manage keys.

## Endpoint

`POST https://api.fetchhive.com/v1/agent/invoke`

If you want Fetch Hive to generate the cURL example for you, open **Agents**, then use **More** -> **Get Code**. If you are already in the editor for a specific agent, click **Code Snippet** instead.

## Request

Use this request shape:

| Field       | Type    | Required | Description                                                                                                                                                                            |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`     | string  | Yes      | The agent ID                                                                                                                                                                           |
| `message`   | string  | Yes      | The message you want to send to the agent                                                                                                                                              |
| `streaming` | boolean | No       | Whether the response should stream back as events                                                                                                                                      |
| `thread_id` | string  | No       | An arbitrary string identifying the conversation thread. Fetch Hive creates a new thread on first use and resumes it on subsequent calls with the same value.                          |
| `messages`  | array   | No       | Previous conversation turns supplied by the caller. Used as context without persisting to the database. Each item: `{ "content": string, "role": "user" \| "assistant" \| "system" }`. |

The in-app snippet shows the same body shape:

```json
{
  "agent": "AGENT_UUID",
  "message": "Your message here",
  "streaming": true
}
```

## Basic example

```bash
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize the latest AI infrastructure trends",
    "streaming": true
  }' \
  --compressed
```

This matches the cURL snippet shown in the product. The invoke dialog currently shows **cURL**, while **Python** and **TypeScript** still show **Coming Soon**.

## Response

If `streaming` is `true`, the route returns a stream of events rather than one final JSON object.

### Streaming response

The stream can include reasoning chunks, response chunks, tool events, and a final usage event.

Reasoning event:

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "response": "Looking at the latest model releases..."
}
```

Response event:

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "response": "Teams are standardizing around evals, routing, and observability.",
  "done": false
}
```

Tool event:

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "tool",
  "tool_id": "tool_123",
  "tool": "google_search",
  "tool_input": {
    "query": "latest AI infrastructure trends 2026"
  },
  "observation": {
    "results": []
  }
}
```

Final usage event:

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
```

### Non-streaming response

If `streaming` is `false`, the route returns one JSON response with the generated output, usage data, and the request ID you can use to inspect the run in **Logs**.

The exact output field can vary by provider, but the response includes the run metadata you need. For example:

```json
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "response": "Teams are moving from simple wrappers to systems with evals, tool routing, and tighter cost controls.",
  "reasoning": "The request asks for a short summary of current infrastructure trends.",
  "usage": {
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

If the agent uses tools, the non-streaming response can also include tool execution details.

## Multi-turn conversations

The invoke endpoint supports two approaches for multi-turn conversations.

### Persistent threads (Fetch Hive manages history)

Pass a `thread_id` — any string you choose — and Fetch Hive will automatically create the thread on the first call and resume it on every subsequent call with the same value. Message history is stored in Fetch Hive and included in the context automatically.

```bash
# First turn
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "What are the main AI infrastructure trends right now?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'

# Second turn — same thread_id resumes the conversation
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'
```

You can use any string as a `thread_id` — a user ID, session ID, ticket number, or any other identifier that makes sense for your use case.

### Stateless history (caller manages history)

If you prefer to manage conversation state yourself, pass the previous turns in the `messages` array. Fetch Hive uses the provided history for context but does not persist it.

```bash
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "messages": [
      { "content": "What are the main AI infrastructure trends right now?", "role": "user" },
      { "content": "Teams are focusing on evals, tool routing, and observability.", "role": "assistant" }
    ]
  }'
```

Use `messages` when you already maintain your own chat state and do not need Fetch Hive to store the conversation history.

## Next steps

* [Logs](https://docs.fetchhive.com/agents/logs)
* [Testing with Chat](https://docs.fetchhive.com/agents/testing-with-chat)
* [Run with Python SDK](https://docs.fetchhive.com/agents/run-with-python-sdk)
* [Run with Node.js SDK](https://docs.fetchhive.com/agents/run-with-nodejs-sdk)