Agents API

The Agents API lets you retrieve information about your deployed AI agents, including their configuration, status, and model assignments. Use this endpoint to discover available agents before sending chat messages.

Endpoint

GET /api/v1/agents

Authentication

Requires a valid API key passed as a Bearer token. See the Authentication docs for details.

Authorization: Bearer $CLAWHQ_API_KEY

Request

This endpoint supports the following optional query parameters for pagination:

Parameter	Type	Default	Description
`limit`	integer	20	Maximum number of agents to return (1-100)
`offset`	integer	0	Number of agents to skip for pagination

Response

A successful request returns a JSON object containing an array of agent objects along with pagination metadata:

{
  "agents": [
    {
      "agent_id": "abc123-def456-ghi789",
      "name": "Support Bot",
      "slug": "support-bot",
      "description": "Handles customer support inquiries with access to the knowledge base",
      "status": "deployed",
      "model": {
        "primary": "k2.5-standard",
        "fallback": "m2.5-mini"
      },
      "deployed_at": "2026-03-10T14:30:00Z"
    },
    {
      "agent_id": "jkl012-mno345-pqr678",
      "name": "Sales Assistant",
      "slug": "sales-assistant",
      "description": "Qualifies leads and answers product questions",
      "status": "deployed",
      "model": {
        "primary": "k2.5-reasoning",
        "fallback": null
      },
      "deployed_at": "2026-03-12T09:15:00Z"
    }
  ],
  "total": 2,
  "has_more": false
}

Response Fields

Field	Type	Description
`agent_id`	string	Unique agent identifier (UUID format)
`name`	string	Human-readable display name of the agent
`slug`	string	URL-safe identifier used in the `agent` parameter of the Chat API
`description`	string	Brief description of the agent's purpose and capabilities
`status`	string	Current status: `deployed`, `stopped`, or `error`
`model.primary`	string	The primary AI model the agent uses for inference
`model.fallback`	string \| null	The fallback model used if the primary is unavailable. Null if no fallback is configured.
`deployed_at`	string (ISO 8601)	Timestamp of the most recent deployment
`total`	integer	Total number of agents matching the query
`has_more`	boolean	Whether there are more agents beyond the current page

Tip: Use the slug field as the agent parameter when calling the Chat API. Slugs are stable identifiers that do not change even if the agent is renamed.

Agent Statuses

Status	Description	Accepts Chat?
`deployed`	Agent is running and accepting messages	Yes
`stopped`	Agent is configured but not currently running	No (returns 404)
`error`	Agent encountered an error and is not accepting messages	No (returns 502)

Code Examples

cURL

curl https://app.clawhq.tech/api/v1/agents?limit=10&offset=0 \
  -H "Authorization: Bearer $CLAWHQ_API_KEY"

Python

import os
import requests

API_KEY = os.environ["CLAWHQ_API_KEY"]

response = requests.get(
    "https://app.clawhq.tech/api/v1/agents",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10, "offset": 0},
)

data = response.json()
for agent in data["agents"]:
    print(f"{agent['name']} ({agent['slug']}) - {agent['status']}")
    print(f"  Model: {agent['model']['primary']}")
    if agent["model"]["fallback"]:
        print(f"  Fallback: {agent['model']['fallback']}")

print(f"Total: {data['total']}, Has more: {data['has_more']}")

JavaScript

const CLAWHQ_API_KEY = process.env.CLAWHQ_API_KEY;

const response = await fetch("https://app.clawhq.tech/api/v1/agents?limit=10&offset=0", {
  headers: {
    "Authorization": `Bearer ${CLAWHQ_API_KEY}`,
  },
});

const data = await response.json();

data.agents.forEach((agent) => {
  console.log(`${agent.name} (${agent.slug}) - ${agent.status}`);
  console.log(`  Model: ${agent.model.primary}`);
  if (agent.model.fallback) {
    console.log(`  Fallback: ${agent.model.fallback}`);
  }
});

console.log(`Total: ${data.total}, Has more: ${data.has_more}`);

Error Responses

Status	Description
`401`	Invalid or missing API key
`403`	Account does not have an active Pro or Ultra plan
`429`	Rate limit exceeded

Next Steps

Chat API — Send messages to your agents
Models API — List available AI models
Authentication — API key management and security