Invoke

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.

Authorization: Bearer YOUR_API_KEY

Agent webhook triggers use the agent webhook secret instead of an API key. See 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.

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:

[
  "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:

{
  "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 <available_files> 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:

{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}

Invalid:

{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

The code snippet dialog uses this body shape:

{
  "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:

{
  "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:

{
  "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:

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

Example response event:

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

Example tool event:

{
  "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:

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

Example error event:

{
  "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.

{
  "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,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}

Example

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

See Authentication for API key setup
See Agents for agent setup and runtime context
See Testing with Chat for the in-editor testing flow
See Run with API for an agent-focused guide

Fetch Hive API

REST API

Authentication

Request body

Webhook trigger

Response

Example

​Authentication

​Request body

​Webhook trigger

​Response

​Example

​Related

Authentication

Request body

Webhook trigger

Response

Example

Related