> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetrident.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API: List and Query Your AI Agent Inventory

> GET /api/public/trident/agents — list all agents registered in your Trident project, with their IDs, cert scores, and open finding counts.

The Agents API gives you a read-only inventory of every AI agent Trident has observed signals for in your project. For each agent you get its latest Trident certificate score, cert status, open finding counts, and the timestamp of its most recent finding. This is the same data the Agents page in the dashboard renders, available programmatically for dashboards, alerting pipelines, and CI gates.

## GET /api/public/trident/agents

Fetch the full agent inventory for your project, sorted by critical finding count descending.

**Endpoint:** `GET https://app.usetrident.dev/api/public/trident/agents`

**Authentication:** HTTP Basic — see [Authentication](/api/authentication)

### Query parameters

<ParamField query="agentId" type="string">
  Filter the response to a single agent by its exact ID. Omit to return all
  agents in the project.
</ParamField>

### Example request

```bash curl theme={null}
CREDENTIALS=$(echo -n "$TRIDENT_PROJECT_PUBLIC_KEY:$TRIDENT_PROJECT_SECRET_KEY" | base64)

curl "https://app.usetrident.dev/api/public/trident/agents" \
  -H "Authorization: Basic $CREDENTIALS" \
  -H "Accept: application/json"
```

### Example response

```json theme={null}
{
  "count": 3,
  "agents": [
    {
      "agentId": "prod-rag-assistant",
      "displayName": null,
      "latestCertScore": 81.5,
      "certStatus": "ACTIVE",
      "openFindings": 4,
      "criticalFindings": 1,
      "lastFindingAt": "2025-06-10T14:22:07.000Z"
    },
    {
      "agentId": "staging-code-reviewer",
      "displayName": null,
      "latestCertScore": 74.0,
      "certStatus": "ACTIVE",
      "openFindings": 2,
      "criticalFindings": 0,
      "lastFindingAt": "2025-06-09T08:54:31.000Z"
    },
    {
      "agentId": "internal-summarizer",
      "displayName": null,
      "latestCertScore": null,
      "certStatus": null,
      "openFindings": 0,
      "criticalFindings": 0,
      "lastFindingAt": null
    }
  ]
}
```

### Response fields

<ResponseField name="count" type="number" required>
  Total number of agents returned.
</ResponseField>

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

  <Expandable title="Agent object fields">
    <ResponseField name="agentId" type="string" required>
      The unique string identifier for this agent, as supplied to
      `trident.init()` or auto-detected from platform environment variables.
    </ResponseField>

    <ResponseField name="displayName" type="string | null" required>
      Human-readable name. Currently `null` — reserved for a future metadata
      API.
    </ResponseField>

    <ResponseField name="latestCertScore" type="number | null" required>
      Score from the most recent Trident certificate, 0–100. `null` if no
      certificate has been issued for this agent yet.
    </ResponseField>

    <ResponseField name="certStatus" type="string | null" required>
      Status of the most recent certificate — for example `"ACTIVE"`,
      `"REVOKED"`, or `"EXPIRED"`. `null` when no certificate exists.
    </ResponseField>

    <ResponseField name="openFindings" type="number" required>
      Count of findings with status `OPEN`, `ACKNOWLEDGED`, or `IN_PROGRESS`.
    </ResponseField>

    <ResponseField name="criticalFindings" type="number" required>
      Count of open findings with severity `CRITICAL`. The array is sorted by
      this field so your highest-risk agents appear first.
    </ResponseField>

    <ResponseField name="lastFindingAt" type="string | null" required>
      ISO 8601 timestamp of the most recent open finding. `null` when the
      agent has no open findings.
    </ResponseField>
  </Expandable>
</ResponseField>

## How agents are registered

Trident builds the agent inventory from two sources:

1. **Findings and certificates** — any agent that has received a red-team finding, a firewall event, or a Trident certificate is automatically added to the inventory. You do not need to register agents manually.

2. **SDK initialisation** — when your agent calls `trident.init({ agentId: "my-agent" })` at startup, Trident registers that agent in your project. The `agentId` string must match the pattern `[a-zA-Z0-9._-]+`.

<Note>
  Agents running on platforms that expose public URLs as environment variables —
  Vercel (`VERCEL_URL`), Fly.io (`FLY_PUBLIC_IP`), Render (`RENDER_EXTERNAL_URL`),
  Railway (`RAILWAY_PUBLIC_DOMAIN`), and Heroku (`HEROKU_APP_NAME`) — are
  auto-registered with their public URL so the Trident scanner can reach them
  without any additional configuration.
</Note>