Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

Pecta tracks every distinct agent_id that appears in an evaluation or ingest request. The two agent management endpoints let you inspect the full list of agents for your organization and optionally pre-register an agent before its first evaluation.
Agents are created automatically on the first call to /v1/evaluate or /v1/ingest that references a new agent_id. Explicit registration via POST /v1/agents is optional — use it when you want the agent to appear in the dashboard before any evaluations have run.

​
GET /v1/agents — list agents

Returns all agents for your organization, sorted by last_seen descending (most recently active first). Up to 500 agents are returned.

​
Endpoint

GET https://api.pecta.ai/v1/agents

​
Authentication

Required. Pass your API key as a Bearer token: 
Authorization: Bearer pk_live_<your-key>

​
Response fields

​
agents
array
Array of agent objects, sorted by last_seen descending.

​
Example request

curl https://api.pecta.ai/v1/agents \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
Example response

{
  "agents": [
    {
      "agent_id": "summarizer-v2",
      "first_seen": "2026-04-10T09:00:00.000Z",
      "last_seen": "2026-05-07T14:22:44.000Z",
      "eval_count": 214
    },
    {
      "agent_id": "bid-agent-prod",
      "first_seen": "2026-03-22T06:15:30.000Z",
      "last_seen": "2026-05-07T13:58:12.000Z",
      "eval_count": 8931
    },
    {
      "agent_id": "content-classifier",
      "first_seen": "2026-05-01T11:00:00.000Z",
      "last_seen": "2026-05-06T17:44:21.000Z",
      "eval_count": 42
    }
  ]
}

​
POST /v1/agents — register an agent

Explicitly registers an agent by ID. If the agent already exists, the call succeeds silently without overwriting any data.

​
Endpoint

POST https://api.pecta.ai/v1/agents

​
Authentication

Required. Pass your API key as a Bearer token: 
Authorization: Bearer pk_live_<your-key>

​
Request body

​
agent_id
string
required
Identifier for the agent to register. Must be between 1 and 200 characters. Use the same value you will pass as agent_id in evaluations.

​
Response fields

The server responds with 201 Created.
​
agent_id
string
The registered agent identifier, echoed back from the request.
​
ok
boolean
Always true on success.

​
Example request

curl --request POST \
  --url https://api.pecta.ai/v1/agents \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "content-classifier" }'

​
Example response

{
  "agent_id": "content-classifier",
  "ok": true
}