REST API Overview | Superagent Docs

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

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

https://superagent.sh/api/v1

Download the OpenAPI 3.1 specification for the complete
machine-readable API contract.

Use the API to create security reports, integrate findings with your own systems, retrieve or scan contributor trust, 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:

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:

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

Reports

List, retrieve, and create repository, Web app, and Agent security reports:

Method	Path	Description
`GET`	`/reports`	List and filter reports
`GET`	`/reports/{report_id}`	Retrieve one report
`POST`	`/reports/repository`	Create a report for a connected GitHub repository
`POST`	`/reports/web-app`	Create a report for a public Web app
`POST`	`/reports/agent`	Create an adversarial Agent report using a Web app or API target

See Reports for request fields, response payloads, and examples.

Findings

Retrieve and manage findings from repository reports, Web app reports, and GitHub advisories:

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 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 for request fields,
response payloads, scan prerequisites, webhook delivery, and examples.

Agents

Register endpoint clients, organize them into groups, distribute YAML security rules, issue pairing tokens, and retrieve alerts:

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

See Agents for the complete endpoint list, payloads, and pairing flow.

Request and response format

Requests with a body must use Content-Type: application/json. Unknown request fields are ignored.

Successful single-resource responses use a data envelope:

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

List responses also include pagination:

{
  "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:

{
  "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://superagent.sh/mcp, using the same API keys. See the MCP server 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.

API