API

Overview

Authenticate with the Superagent REST API and understand its common request and response format.

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

https://superagent.sh/api/v1

Use the API to create security reports, integrate findings with your own systems, 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

Create repository and Web app security reports:

Method Path Description
POST /reports/repository Create a report for a connected GitHub repository
POST /reports/web-app Create a report for a public Web app

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.

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

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