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

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

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 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 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, 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 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 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 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:

{
  "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://www.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

• Start Red Team runs with the Reports API
• Manage findings with the Findings API
• Use Superagent MCP