Run with API

Invoke an agent with the public API using your workspace API key, an agent ID, and a message

Use the public agent invoke endpoint when you want to send a message to an agent from your own app or service. In Fetch Hive, you can copy the request shape from More -> Get Code in the agents sidebar or from Code Snippet in the agent editor.

Authentication

Authorization: Bearer YOUR_API_KEY

See API Keys for how to create and manage keys.

Endpoint

POST https://api.fetchhive.com/v1/agent/invoke

If you want Fetch Hive to generate the cURL example for you, open Agents, then use More -> Get Code. If you are already in the editor for a specific agent, click Code Snippet instead.

Request

Use this request shape:

Field	Type	Required	Description
agent	string	Yes	The agent ID
message	string	Yes	The message you want to send to the agent
streaming	boolean	No	Whether the response should stream back as events

The in-app snippet shows the same body shape:

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

Basic 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",
    "streaming": true
  }' \
  --compressed

This matches the cURL snippet shown in the product. The invoke dialog currently shows cURL, while Python and TypeScript still show Coming Soon.

Response

If streaming is true, the route returns a stream of events rather than one final JSON object.

Streaming response

The stream can include reasoning chunks, response chunks, tool events, and a final usage event.

Reasoning event:

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

Response event:

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

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

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

Non-streaming response

If streaming is false, the route returns one JSON response with the generated output, usage data, and the request ID you can use to inspect the run in Logs.

The exact output field can vary by provider, but the response includes the run metadata you need. For example:

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

If the agent uses tools, the non-streaming response can also include tool execution details.

Next steps

• Logs

• Testing with Chat

• Run with Python SDK

• Run with Node.js SDK