> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoke > Send a message to an agent with the public Fetch Hive API using an agent ID and message `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 theme={null} Authorization: Bearer YOUR_API_KEY ``` Agent webhook triggers use the agent webhook secret instead of an API key. See [Webhook trigger](#webhook-trigger). ## Request body Open an agent in the editor and click **Code Snippet** to see the current public request shape in Fetch Hive. ## Webhook trigger `POST /v1/agent/webhooks/{agent_id}` Use an agent webhook trigger when an external service should start an agent run without a workspace API key. The request must include the agent webhook secret in `X-Fetch-Hive-Webhook-Secret`. If a third-party tool cannot set custom headers, use `?secret=YOUR_WEBHOOK_SECRET` as a fallback. Agent webhook triggers always use callback delivery. Include `async.callback_url`; Fetch Hive returns `202` with `request_id` and `run_status: "running"`, then delivers either `agent.completed` or `agent.failed` to the callback URL. ```bash theme={null} curl 'https://api.fetchhive.com/v1/agent/webhooks/YOUR_AGENT_ID' \ -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \ -H 'Content-Type: application/json' \ --data-raw '{ "message": "Summarize the latest ticket", "thread_id": "external-thread-123", "metadata": { "customer_id": "cus_123", "plan": "enterprise" }, "user": "external-user-1", "async": { "callback_url": "https://example.com/callback" } }' ``` `message` is required. `thread_id` is optional and can be reused to resume a caller-managed thread. `metadata` follows the same flat scalar-only rule as normal agent invokes and appears in log filtering. Fetch Hive signs the outbound callback with the same webhook secret used for inbound trigger authentication. Callback `data` contains `response` on `agent.completed` and `error` on `agent.failed`; use the top-level `event_type` and `request_id` for terminal state and correlation. | 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", "attachments"?: array }`. Use this when you manage conversation state yourself. | | `attachments` | array | No | HTTPS file URLs attached to the current `message`. Each item can be a URL string or an object with `file_url`. Supported document files are CSV, XLSX, PDF, DOCX, and text/Markdown by extension. Images can also be passed here. | | `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not added to the agent prompt. | `metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`. Arrays and nested objects are rejected before the run starts. `attachments` items can be simple URL strings: ```json theme={null} [ "https://example.com/customer-brief.pdf", "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v" ] ``` They can also use this object shape when you want to provide metadata: ```json theme={null} { "file_url": "https://example.com/customer-brief.pdf", "file_name": "customer-brief.pdf", "file_type": "application/pdf" } ``` Only `https://` URLs are accepted. Up to five attachments are allowed per message. Document attachments are exposed to the agent through the system `read_file` tool as an `` manifest; the agent calls `read_file` before relying on document contents. Image attachments are sent to the model as multimodal input. For image URLs without a file extension, use the object shape with `file_type` set to an image MIME type (for example `image/png`). If an attachment URL or type is invalid, Fetch Hive returns `422 Unprocessable Entity` instead of opening the stream. Supported document attachments: * CSV: `text/csv`, `.csv` * XLSX: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `.xlsx` * PDF: `application/pdf`, `.pdf` * DOCX: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `.docx` * Text and Markdown by extension: `.txt`, `.md`, `.markdown` For extensionless URLs, such as Fetch Hive Media Library URLs, pass the URL directly. Fetch Hive allow-lists the URL for `read_file`, and the file tool detects the actual type when it fetches the file. Valid: ```json theme={null} { "metadata": { "customer_id": "cus_123", "plan": "enterprise", "trial": false, "invoice_count": 12, "region": null } } ``` Invalid: ```json theme={null} { "metadata": { "customer": { "id": "cus_123" }, "tags": ["enterprise"] } } ``` The code snippet dialog uses this body shape: ```json theme={null} { "agent": "AGENT_UUID", "message": "Your message here", "streaming": true, "attachments": [ "https://example.com/customer-brief.pdf" ], "metadata": { "customer_id": "cus_123", "plan": "enterprise" } } ``` When using `thread_id` for persistent conversations: ```json theme={null} { "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 theme={null} { "agent": "AGENT_UUID", "message": "What else should I know?", "streaming": true, "messages": [ { "content": "What are the latest AI trends?", "role": "user", "attachments": [ "https://example.com/market-data.csv" ] }, { "content": "Teams are focusing on evals, routing, and observability.", "role": "assistant" } ] } ``` If a previous assistant turn generated a file, pass that file back on the relevant history message through `messages[].attachments`. Fetch Hive uses the structured attachment URLs in current and historical messages to authorize `read_file` access for follow-up turns; URLs mentioned only in plain text are not treated as file-tool attachments. ## Response If `streaming` is `true`, Fetch Hive returns a stream of events. If the provider fails after the stream has opened, Fetch Hive sends a final `error` event before closing the stream. If the client disconnects first, Fetch Hive treats it as a silent cancellation and does not create a failed agent run, bill usage, or report a provider-error event unless the provider had already completed and usage was committed. Example reasoning event: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "reasoning", "response": "Looking at the latest model releases..." } ``` Example response event: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "response", "response": "Teams are standardizing around evals, routing, and observability.", "done": false } ``` Example tool event: ```json theme={null} { "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 theme={null} { "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" } ``` Example error event: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "error", "id": "msg_019d52846ea37682b03522fd0695cc43", "error": "openai provider stream error: HTTP 400: invalid request", "message": "openai provider stream error: HTTP 400: invalid request", "provider": "openai", "error_type": "provider_stream_error", "status_code": 502 } ``` If `streaming` is `false`, Fetch Hive returns one JSON response. Provider execution failures return `502 Bad Gateway` with an `error` message. ```json theme={null} { "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 theme={null} 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", "metadata": { "customer_id": "cus_123", "plan": "enterprise" }, "streaming": true }' \ --compressed ``` ## Related * See [Authentication](./authentication) for API key setup * See [Agents](../agents/overview) for agent setup and runtime context * See [Testing with Chat](../agents/testing-with-chat) for the in-editor testing flow * See [Run with API](../agents/run-with-api) for an agent-focused guide