Agents API

Interact with your workspace's agent swarm — list available agents and invoke them via the REST API.

List Agents

GET /api/v1/agents

Returns all enabled agents in your workspace.

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Code Reviewer",
      "description": "Reviews code for bugs and best practices",
      "modelTier": "balanced",
      "isDefault": false,
      "tools": ["lint_code", "search_docs"]
    }
  ]
}

Example

curl -H "Authorization: Bearer cg_YOUR_KEY" \
  https://cognova.dev/api/v1/agents

Ask an Agent

POST /api/v1/agents/ask

Send a message to a specific agent and receive a response. The agent runs with its full tool set and knowledge base, executing a multi-turn loop if needed.

Request Body

Field	Type	Required	Description
`agent_id`	string	No	Agent UUID. Omit to use the default agent
`message`	string	Yes	The message to send

Response

{
  "data": {
    "response": "Here's my analysis of your code...",
    "model": "claude-sonnet-4-20250514",
    "tokens": {
      "input": 1523,
      "output": 847
    }
  }
}

Example

# Ask the default agent
curl -X POST https://cognova.dev/api/v1/agents/ask \
  -H "Authorization: Bearer cg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are the active tasks?"}'

# Ask a specific agent
curl -X POST https://cognova.dev/api/v1/agents/ask \
  -H "Authorization: Bearer cg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_UUID", "message": "Review this code"}'

Notes

Agent invocations consume credits based on the agent's model tier
The agent has access to all its bound tools and knowledge
If the agent uses delegation tools (ask_[name]), those sub-agent calls also consume credits
Token usage is logged with source mcp in the billing dashboard