Invoke Agent

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.

Authorization: Bearer YOUR_API_KEY

Request body

Open an agent in the editor and click Code Snippet to see the current public request shape in Fetch Hive.

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

The code snippet dialog uses this body shape:

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

Response

If streaming is true, Fetch Hive returns a stream of events.

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

If streaming is false, Fetch Hive returns one JSON response.

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

Related

• See Authentication for API key setup

• See Agents for agent resource endpoints

• See Testing with Chat for the in-editor testing flow

• See Run with API for an agent-focused guide