> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Authenticate with the Superagent REST API and manage reports, findings, contributor trust, context scores, and monitored agents.

# REST API

The Superagent REST API uses versioned URLs under `/api/v1`. The base URL is:

```text
https://superagent.sh/api/v1
```

Download the [OpenAPI 3.1 specification](https://www.superagent.sh/openapi/v1.yaml) for the complete
machine-readable API contract.

Use the API to start Red Team runs, retrieve red-team reports, integrate findings with your own systems, retrieve or scan contributor trust, score Web pages, email, messages, files, skills, MCP repositories, and registry packages before agents consume them, and start automated triage.

## Authentication

Create and revoke organization API keys from **Settings** (`/app/settings`). Send the key as a bearer token in the `Authorization` header of every request:

```bash
curl https://superagent.sh/api/v1/findings \
  -H "Authorization: Bearer sk_live_..."
```

The `/api/v1` endpoints do not accept the key in an `x-api-key` header or query parameter. An API key grants access to all API resources in its organization, including permanent finding deletion and starting billable report or triage work. Keep it secret and revoke it immediately if it is exposed.

Authentication failures return `401`:

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide a valid API key using Authorization: Bearer <api_key>"
  }
}
```

## Reports

Start repository, application, Agent, and Package Red Team runs, then list and retrieve their red-team reports:

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/reports` | List and filter red-team reports |
| `GET` | `/reports/{report_id}` | Retrieve one red-team report |
| `POST` | `/reports/repository` | Start a run for a connected GitHub repository |
| `POST` | `/reports/web-app` | Start a run for a public application |
| `POST` | `/reports/agent` | Start an Agent run using an application or API target |
| `POST` | `/reports/package` | Start a run for an installable package or local software target |

See [Reports](https://www.superagent.sh/docs/api/reports) for request fields, response payloads, and examples.

## Findings

Retrieve and manage findings from Superagent security workers, customer-provided
security agents, and connected advisory sources:

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/findings` | List and filter findings |
| `GET` | `/findings/{finding_id}` | Retrieve full finding context |
| `PATCH` | `/findings/{finding_id}` | Update a finding's triage state |
| `DELETE` | `/findings/{finding_id}` | Permanently delete a finding |
| `POST` | `/findings/{finding_id}/triage` | Start automated triage |

See [Findings](https://www.superagent.sh/docs/api/findings) for pagination, payload schemas, lifecycle rules, and examples.

## Contributor Trust

Retrieve the latest globally cached trust result for a GitHub login, or start and
track a new organization-scoped scan:

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/contributors/{login}/trust` | Retrieve the latest cached result; returns `404` when none exists |
| `POST` | `/contributors/{login}/trust-scans` | Start an asynchronous scan |
| `GET` | `/contributor-trust-scans/{scan_id}` | Retrieve an organization-scoped scan and its result |

See [Contributor Trust](https://www.superagent.sh/docs/api/contributor-trust) for request fields,
response payloads, scan prerequisites, webhook delivery, and examples.

## Context Guardrails

Score a web page, email, message, file, agent skill, MCP repository, or registry package before an agent consumes it. Results are cached
globally; each request is logged to the API key's organization:

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/context/web_page/{identifier}` | Score a web page |
| `POST` | `/context/email` | Score a raw RFC 822 email |
| `GET` | `/context/email/{identifier}` | Look up a scored email by SHA-256 |
| `POST` | `/context/message` | Score text and outbound HTTPS links from an SMS or WhatsApp message |
| `GET` | `/context/message/{identifier}` | Look up a scored message by SHA-256 |
| `POST` | `/context/file` | Score a public text or PDF file |
| `GET` | `/context/file/{identifier}` | Look up a scored file by SHA-256 |
| `POST` | `/context/skill` | Statically score a skills.sh or GitHub hosted skill |
| `GET` | `/context/skill/{identifier}` | Look up a scored skill by SHA-256 |
| `POST` | `/context/mcp` | Statically score a public GitHub MCP repository |
| `GET` | `/context/mcp/{identifier}` | Look up a scored MCP repository by SHA-256 |
| `POST` | `/context/package` | Score a registry package |
| `GET` | `/context/package/{identifier}` | Look up a scored package by SHA-256 |

See [Context Guardrails](https://www.superagent.sh/docs/api/context-guardrails) for query parameters,
verdicts, tolerance, and examples.

## Applications

Create persistent application targets, connect source repositories, and
configure encrypted credentials, request throttling, specific prompts, and
recurring red-team schedules through `/applications`.

See [Applications](https://www.superagent.sh/docs/api/applications) for endpoint payloads and examples.

## Agents

Create persistent Agent assets, configure red-team targets and schedules,
register runtime clients, organize them into groups, distribute YAML security
rules, issue pairing tokens, and retrieve alerts:

| Resource | Base endpoint |
| --- | --- |
| Agents | `/agents` |
| Clients | `/agents/clients` |
| Groups | `/agents/groups` |
| Rules | `/agents/rules` |
| Alerts | `/agents/records` |

See [Agents](https://www.superagent.sh/docs/api/agents) for the complete endpoint list, payloads, and pairing flow.

## Request and response format

Requests with a body must use `Content-Type: application/json`. The
`POST /context/email` endpoint also accepts a raw RFC 822 body as
`message/rfc822` or `text/plain`. Structured email and message requests reject
unsupported JSON fields; other endpoints ignore unknown JSON fields unless
their reference says otherwise.

Successful single-resource responses use a `data` envelope:

```json
{
  "data": {
    "id": "resource_uuid",
    "object": "finding"
  }
}
```

List responses also include pagination:

```json
{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}
```

Dates use ISO 8601 strings in UTC. Optional values that are unavailable are returned as `null`; optional arrays are returned as empty arrays.

## Errors

Errors use an `error` object with a stable machine-readable `code` and a human-readable `message`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100"
  }
}
```

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Invalid JSON, field, query parameter, or state transition |
| `401` | `unauthorized` | Missing, malformed, unknown, or revoked API key |
| `404` | `not_found` | Resource does not exist or belongs to another organization |
| `409` | `conflict` | Requested work is already in progress |
| `500` | `internal_error` | Unexpected server failure |

## Use the API from an AI coding agent

Every endpoint above is also exposed as an MCP tool at
`https://www.superagent.sh/mcp`, using the same API keys. See the [MCP
server](https://www.superagent.sh/docs/mcp) guide to connect Cursor, Claude Code, or Codex CLI.

## Legacy finding endpoint

`GET /api/findings/{finding_id}` continues to accept `x-api-key` for existing webhook integrations. New integrations should use `GET /api/v1/findings/{finding_id}` with bearer authentication.

## Next steps

- [Start Red Team runs with the Reports API](https://www.superagent.sh/docs/api/reports)
- [Manage findings with the Findings API](https://www.superagent.sh/docs/api/findings)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)

---
Source: https://www.superagent.sh/docs/api
Index: https://www.superagent.sh/llms.txt