> ## 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.

# GET and POST /v1/agents — manage agents

> List all agents in your organization or register one by ID. Agents are created automatically on first evaluation — explicit registration is optional.

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.

<Note>
  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.
</Note>

## 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

<ResponseField name="agents" type="array">
  Array of agent objects, sorted by `last_seen` descending.

  <Expandable title="Agent fields">
    <ResponseField name="agents[].agent_id" type="string">
      Unique agent identifier within your organization.
    </ResponseField>

    <ResponseField name="agents[].first_seen" type="string">
      ISO 8601 UTC timestamp of the first evaluation recorded for this agent.
    </ResponseField>

    <ResponseField name="agents[].last_seen" type="string">
      ISO 8601 UTC timestamp of the most recent evaluation.
    </ResponseField>

    <ResponseField name="agents[].eval_count" type="number">
      Total number of evaluations recorded for this agent.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example request

```bash theme={null}
curl https://api.pecta.ai/v1/agents \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Example response

```json theme={null}
{
  "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

<ParamField body="agent_id" type="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.
</ParamField>

### Response fields

The server responds with `201 Created`.

<ResponseField name="agent_id" type="string">
  The registered agent identifier, echoed back from the request.
</ResponseField>

<ResponseField name="ok" type="boolean">
  Always `true` on success.
</ResponseField>

### Example request

```bash theme={null}
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

```json theme={null}
{
  "agent_id": "content-classifier",
  "ok": true
}
```