Skip to main content
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.
FieldTypeRequiredDescription
agentstringYesThe agent ID
messagestringYesThe message you want to send
streamingbooleanNoStream response events instead of waiting for one final JSON response
thread_idstringNoAn 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.
messagesarrayNoPrevious conversation turns to use as context without persisting history to the database. Each item: { "content": string, "role": "user" | "assistant" | "system", "attachments"?: array, "image_urls"?: array }. Use this when you manage conversation state yourself.
attachmentsarrayNoHTTPS 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.
image_urlsarrayNoBackward-compatible shorthand for HTTPS image attachments on the current message. Use this for image-only integrations, especially when the image URL has no extension.
metadataobjectNoFlat 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, counting both attachments and image_urls. 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. 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. 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
    },
    "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
    },
    "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