# Invoke Agent

`POST /v1/agent/invoke`

Send a message to an agent from your own app or service.

## Authentication

Send your workspace API key in the `Authorization` header.

```bash
Authorization: Bearer YOUR_API_KEY
```

## Request body

Open an agent in the editor and click **Code Snippet** to see the current public request shape in Fetch Hive.

| Field       | Type    | Required | Description                                                                                                                                                                                                                    |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent`     | string  | Yes      | The agent ID                                                                                                                                                                                                                   |
| `message`   | string  | Yes      | The message you want to send                                                                                                                                                                                                   |
| `streaming` | boolean | No       | Stream response events instead of waiting for one final JSON response                                                                                                                                                          |
| `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. Ideal for persistent, multi-turn conversations.                  |
| `messages`  | array   | No       | Previous conversation turns to use as context without persisting history to the database. Each item: `{ "content": string, "role": "user" \| "assistant" \| "system" }`. Use this when you manage conversation state yourself. |

The code snippet dialog uses this body shape:

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

When using `thread_id` for persistent conversations:

```json
{
  "agent": "AGENT_UUID",
  "message": "What did we discuss last time?",
  "streaming": true,
  "thread_id": "user-456-support-session"
}
```

When using `messages` for caller-managed (stateless) history:

```json
{
  "agent": "AGENT_UUID",
  "message": "What else should I know?",
  "streaming": true,
  "messages": [
    { "content": "What are the latest AI trends?", "role": "user" },
    { "content": "Teams are focusing on evals, routing, and observability.", "role": "assistant" }
  ]
}
```

## Response

If `streaming` is `true`, Fetch Hive returns a stream of events.

Example reasoning event:

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

Example response event:

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

Example 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": []
  }
}
```

Example 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"
}
```

If `streaming` is `false`, Fetch Hive returns one JSON response.

```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"
}
```

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

## Related

* See [Authentication](https://docs.fetchhive.com/api-reference/authentication) for API key setup
* See [Agents](https://github.com/Jellyfishboy/fetchhive-api/blob/app-v3/LIVE_DOCS/api-reference/agents.md) for agent resource endpoints
* See [Testing with Chat](https://docs.fetchhive.com/agents/testing-with-chat) for the in-editor testing flow
* See [Run with API](https://docs.fetchhive.com/agents/run-with-api) for an agent-focused guide