Docs / agents-api

Agents and MCP servers API

← All docs

The agents endpoint exposes the tenant's catalogue of AI agents and MCP (Model Context Protocol) servers. Each record carries the tool count, sync state, and the AI application it belongs to.

GET /api/v2/agents

curl -sS "https://penaxtra.com/api/v2/agents" \
  -H "Authorization: Bearer $TOKEN"

Required scope: agents:read.

Response

{
  "data": [
    {
      "id": "<uuid>",
      "name": "Underwriting copilot",
      "kind": "agent",
      "url": "https://internal-agent.example/v1/agent",
      "status": "active",
      "source": "manual",
      "tools_count": 7,
      "agent_last_synced_at": "2026-05-22T10:14:00Z",
      "agent_sync_error": null,
      "ai_application_id": "<uuid>",
      "created_at": "2026-04-08T08:00:00Z"
    }
  ]
}

Fields

FieldNotes
kindagent or mcp_server.
sourcemanual, openapi, langchain, bedrock, mcp_introspection.
tools_countNumber of tools currently registered against the agent or MCP server.
agent_last_synced_atLast time the tool catalogue was fetched from upstream.
agent_sync_errorFree-text last error from sync, or null if the most recent attempt succeeded.
ai_application_idThe AI application this agent belongs to; null when the agent is unaffiliated.

Notes

  • Newest record first; result set capped at 200 rows.
  • Tool-level catalogue (per-agent tool descriptions and HITL state) is exposed by the console today; the per-tool list endpoint (GET /api/v2/agents/{id}/tools) is planned.
  • POST /api/v2/agents/{id}/sync to refresh the tool catalogue is planned; today sync runs on the console-driven cron.

Related

Last reviewed: 2026-06-13. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .