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 agent.completed, agent.failed, or agent.awaiting_approval 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. Add response_format to the webhook body to get JSON back. It is the same object as the JSON output field on invoke, and it applies to this call only. Omit it and the callback carries text.

{
  "message": "List three competitors",
  "async": { "callback_url": "https://example.com/callback" },
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "competitors",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "competitors": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["competitors"],
        "additionalProperties": false
      }
    }
  }
}

agent.completed keeps data.response as the JSON text and adds data.output_json, the parsed object. output_json is not sent on agent.awaiting_approval or agent.failed.

{
  "event_type": "agent.completed",
  "request_id": "req_123",
  "data": {
    "response": "{\"competitors\":[\"Acme\",\"Globex\",\"Initech\"]}",
    "output_json": { "competitors": ["Acme", "Globex", "Initech"] }
  }
}

If the schema is invalid, the model cannot return JSON Schema, or the answer still does not match after one retry, the run fails and Fetch Hive delivers agent.failed with the error in data.error. 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. agent.awaiting_approval includes pending_tool_approvals and a dashboard review_url. A later agent.completed includes resumed_from_run_id when the run continued after approval. See Tool approvals.

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.
`decided_tool_approvals`	array	No	Approval ids from an earlier `awaiting_approval` response. Each item is `{ "approval_id": string }`. API key calls resume on the server; do not send this. A first-party streaming client re-invokes the same `thread_id`. See Tool approvals.
`tool_approval`	string	No	`policy` or `auto_approve`. Omit it, or send `policy`, to follow workspace rules and any saved auto-approve switch. `auto_approve` applies to this call only when the API key is allowed to auto-approve actions. Any other value returns `400` `invalid_tool_approval` before the run starts.
`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.
`async`	object	No	Background workflow options. `callback_url` receives a signed `agent.delegation.completed` event. `allow_background` defaults to true when `thread_id` is set or `callback_url` is present, and false otherwise.

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://example.com/customer-brief.pdf"
]

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.

Auto-approve for one call

tool_approval: "auto_approve" is accepted only from an API key whose owner or admin has turned on “Allow this key to auto-approve actions” in Settings → API keys. The call does not change the agent’s saved setting and does not write a policy. A key without that permission, a signed-in editor token, and a webhook all return 403 before any model call, preflight, or billing:

{
  "error_code": "tool_approval_override_not_permitted",
  "error": "This API key is not allowed to auto-approve actions. A workspace owner or admin can enable it in Settings → API keys.",
  "message": "This API key is not allowed to auto-approve actions. A workspace owner or admin can enable it in Settings → API keys."
}

When auto-approve is turned off for the workspace, the same error_code is returned with the message Auto-approve is not available for this workspace. Destructive actions still ask. Deny rules still block the action. A sub-agent started by this call receives the same tool_approval and the same API key. A workflow the agent starts does not. A successful response echoes tool_approval as auto_approve or policy. When an action ran because of an override, the body also includes auto_approved_tool_calls: [{ "summary": string, "tool_name": string }]. A streaming call puts both fields on the final usage event.

JSON output

response_format belongs to this call. Omit it and the agent returns text. Send a schema and the same agent returns JSON.

{
  "agent": "YOUR_AGENT_ID",
  "message": "List three competitors",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "competitors",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "competitors": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["competitors"],
        "additionalProperties": false
      }
    }
  }
}

type is json_schema or text. The schema root must be an object. The schema document must be at most 100000 bytes. When strict is omitted or true, each object node is stored with additionalProperties: false. strict: false leaves the schema as you sent it. Older clients may send is_json_schema_response_format: true plus json_schema instead. When both shapes are present, response_format wins. A model that does not support JSON Schema returns 422 json_schema_unsupported before the run starts. A schema that is not an object, or is larger than 100000 bytes, returns 422 json_schema_invalid. The schema applies to the final answer. Tool calls still run. If that answer does not match the schema, Fetch Hive asks for the answer once more. A second failure returns 422 json_schema_output_invalid. The message saved on the thread is the JSON text. A non-streaming response keeps response as that JSON text and adds output_json, the parsed object. A streaming call still sends text deltas as they arrive. The final usage event includes output_json. Use output_json when a repair replaced the text after those deltas. response_format also works on agent webhook triggers. The callback then carries output_json on agent.completed.

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",
  "status": "completed",
  "run_id": "req_019d52846ea37682b03522fd0695cc43",
  "thread_id": null
}

Example tool approval event:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "tool_approval",
  "approval": {
    "type": "tool_approval",
    "approval_id": "0b6c8f0e-0000-4000-8000-000000000001",
    "summary": "Send a Slack message to #general",
    "expires_at": "2026-10-07T01:00:00Z",
    "tool_name": "SLACK_SEND_MESSAGE",
    "status": "pending"
  },
  "done": false
}

Example final usage event when waiting for approval:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "input_tokens": { "total_tokens": 24 },
    "output_tokens": { "total_tokens": 40 },
    "total_tokens": 64
  },
  "stop_reason": "completed",
  "status": "awaiting_approval",
  "run_id": "req_019d52846ea37682b03522fd0695cc43",
  "thread_id": "ticket-42",
  "pending_tool_approvals": [
    {
      "approval_id": "0b6c8f0e-0000-4000-8000-000000000001",
      "tool_name": "SLACK_SEND_MESSAGE",
      "summary": "Send a Slack message to #general",
      "arguments": { "channel": "#general", "text": "hello" },
      "expires_at": "2026-10-07T01:00:00Z",
      "review_url": "https://app.fetchhive.com/WORKSPACE_ID/approvals?approval=0b6c8f0e-0000-4000-8000-000000000001"
    }
  ]
}

status and run_id are always present. thread_id is the value you sent, or null. pending_tool_approvals is present only when status is awaiting_approval. denied_tool_calls is present only when a policy denied a call in the turn. stop_reason stays the provider value. See Tool approvals. 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",
  "status": "completed",
  "run_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "thread_id": null
}

A paused non-streaming response uses the same pending_tool_approvals shape as the usage event above, and the response text includes [Waiting for approval: …].

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

Auto-approve for one call

JSON output

Response

Example

​Authentication

​Request body

​Webhook trigger

​Auto-approve for one call

​JSON output

​Response

​Example

​Related

Authentication

Request body

Webhook trigger

Auto-approve for one call

JSON output

Response

Example

Related