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, score web pages, email, 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:

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.

Context Guardrails

Score a web page, email, 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/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 for query parameters,
verdicts, tolerance, 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, except
POST /context/email, which accepts a raw RFC 822 body
(message/rfc822 or text/plain). Unknown JSON 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.

Next steps

• Reports
• Findings
• Contributor Trust
• Context Guardrails
• Agents
• MCP server
• Webhooks
• Settings