// interfaces
Reports
Start repository, application, Agent, Package, and Image validation runs, then retrieve their red-team reports through the REST API.
Start repository, application, Agent, Package, and Image validation runs with organization API keys, then list and retrieve their red-team reports. Creation endpoints start billable work and return 202 Accepted while sandbox provisioning continues.
All requests require the Bearer authentication described in the REST API.
List reports
GET /api/v1/reports returns repository, application, Agent, Package, and Image reports for the API key's organization, newest first. For repository, application, Agent, and Package reports, completed indicates review completion, not scan completion; Agent runs expose their scan-finished state as in_review until the report review is complete.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 25 |
Number of results to return, from 1 through 100 |
offset |
integer | 0 |
Number of matching results to skip |
type |
string | none | Restrict results to repository, web_app, agent, package, or image |
image_id |
UUID | none | Restrict results to a monitored image; compatible with type=image |
status |
string | none | Restrict results to in_progress, in_review, completed, done, failed, or image execution states queued, provisioning, running, cancelled |
curl "https://superagent.sh/api/v1/reports?type=repository&status=done&limit=2" \
-H "Authorization: Bearer sk_live_..."Response
{
"data": [
{
"id": "report_uuid",
"object": "report",
"type": "repository",
"repository": "https://github.com/acme/web",
"custom_goal_prompt": null,
"status": "done",
"sandbox_status": "ready",
"agent_status": "completed",
"created_at": "2026-07-22T07:00:00.000Z",
"updated_at": "2026-07-22T09:00:00.000Z"
}
],
"pagination": {
"limit": 2,
"offset": 0,
"total": 1,
"has_more": false
}
}All report types are interleaved by creation time. Each entry carries a type field, and its remaining fields match the creation response for that report type.
Retrieve a report
GET /api/v1/reports/{report_id} returns a single repository, application, Agent, or Package report.
curl https://superagent.sh/api/v1/reports/report_uuid \
-H "Authorization: Bearer sk_live_..."The response is a data envelope containing one report object. Reports belonging to another organization return 404 not_found.
Update report review status
PATCH /api/v1/reports/{report_id} manually marks a successfully finished report Completed or returns it to In Review. This works for repository, application, Agent, and Package reports within the API key's organization.
| Field | Type | Required | Description |
|---|---|---|---|
status |
string | Yes | completed or in_review; no other fields can be updated |
curl https://superagent.sh/api/v1/reports/report_uuid \
-X PATCH \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"status":"completed"}'The response is 200 OK with the updated report in a data envelope, using the same fields as the retrieve endpoint. Send {"status":"in_review"} to reopen review. Running, provisioning, and failed scans cannot be manually completed or reopened and return 409 conflict. Automated reports must have a successfully finished agent; manual Agent reports must have finished their run. Missing reports and reports outside the API key's organization return 404 not_found.
You can complete a review even with unresolved findings. This changes only the report's review status; it does not run or stop a scan, change individual finding resolutions, or trigger a new report.finished webhook.
Automatic completion works through the API too: resolving every finding with the Findings API completes the report, and new or reopened unresolved findings return it to In Review. A successful scan with no findings completes automatically. Legacy Agent test results do not affect automatic completion; only Agent advisories count.
The equivalent MCP tool is update_report_review_status(report_id, status). Both interfaces expose the public values completed and in_review for reviewable report types, including Agent reports. Image validation reports do not have a separate review status.
Start a repository run
POST /api/v1/reports/repository creates a report for a repository connected to the API key's organization.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
repository |
string | Yes | Connected repository as owner/name or a full GitHub URL; maximum 512 characters |
custom_goal_prompt |
string or null | No | Additional test goal; maximum 8,000 characters |
curl https://superagent.sh/api/v1/reports/repository \
-X POST \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"repository": "acme/web",
"custom_goal_prompt": "Focus on authorization boundaries."
}'Response
202 Accepted
{
"data": {
"id": "report_uuid",
"object": "report",
"type": "repository",
"repository": "https://github.com/acme/web",
"custom_goal_prompt": "Focus on authorization boundaries.",
"status": "in_progress",
"sandbox_status": "provisioning",
"agent_status": "pending",
"created_at": "2026-07-22T07:00:00.000Z",
"updated_at": "2026-07-22T07:00:00.000Z"
}
}| Field | Type | Description |
|---|---|---|
id |
string | Report UUID |
object |
string | Always report |
type |
string | Always repository |
repository |
string | Normalized GitHub repository URL |
custom_goal_prompt |
string or null | Additional test goal |
status |
string | Report lifecycle status |
sandbox_status |
string | Sandbox provisioning status |
agent_status |
string | Security agent status |
created_at |
string | Creation time |
updated_at |
string | Last update time |
If the repository is not connected to the organization, the API returns 404 not_found.
Start an application run
POST /api/v1/reports/web-app starts a Red Teaming run for a public HTTP or HTTPS
target.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
target_url |
string | Yes | Public HTTP or HTTPS URL to test; maximum 2,048 characters |
login_email |
string or null | No | Login email for the test account; maximum 320 characters |
login_password |
string or null | No | Login password for the test account; maximum 4,096 characters |
browser_headers |
object or null | No | Custom browser header names and string values |
request_throttle_rpm |
integer, numeric string, or null | No | Maximum requests per minute, from 1 through 600 |
custom_goal_prompt |
string or null | No | Additional test goal; maximum 8,000 characters |
browser_headers supports up to 20 entries. Header names must be unique case-insensitively and use valid HTTP token names with at most 128 characters. Values must be non-empty strings with at most 4,096 characters and cannot contain line breaks.
curl https://superagent.sh/api/v1/reports/web-app \
-X POST \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://staging.example.com/account",
"login_email": "security-test@example.com",
"login_password": "secret",
"browser_headers": {
"X-Test-Environment": "security"
},
"request_throttle_rpm": 120,
"custom_goal_prompt": "Focus on account authorization."
}'Response
202 Accepted
{
"data": {
"id": "report_uuid",
"object": "report",
"type": "web_app",
"target_url": "https://staging.example.com/account",
"allowed_host": "staging.example.com",
"request_throttle_rpm": 120,
"custom_goal_prompt": "Focus on account authorization.",
"status": "in_progress",
"sandbox_status": "provisioning",
"agent_status": "pending",
"created_at": "2026-07-22T07:00:00.000Z",
"updated_at": "2026-07-22T07:00:00.000Z"
}
}| Field | Type | Description |
|---|---|---|
id |
string | Report UUID |
object |
string | Always report |
type |
string | Always web_app |
target_url |
string | Normalized target URL |
allowed_host |
string | Host the security agent is allowed to test |
request_throttle_rpm |
integer or null | Configured request limit |
custom_goal_prompt |
string or null | Additional test goal |
status |
string | Report lifecycle status |
sandbox_status |
string | Sandbox provisioning status |
agent_status |
string | Security agent status |
created_at |
string | Creation time |
updated_at |
string | Last update time |
Credentials and browser headers are encrypted at rest and are never returned. File attachments are not supported by this JSON endpoint.
Start an Agent run
POST /api/v1/reports/agent starts adversarial testing against an AI agent through either an application or API endpoint.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
target_type |
web_app or api |
Yes | Interaction modality used by the red-team runner |
target_url |
string | Yes | Public application or API endpoint URL; maximum 2,048 characters |
agent_type |
string | No | chatbot (default), voice_agent, coding_agent, ai_workflow, data_pipeline, or other |
description |
string or null | No | Report label; defaults to the target host |
login_email |
string or null | No | Login email for application targets |
login_password |
string or null | No | Login password for application targets |
headers |
object or null | No | Encrypted HTTP headers sent to either target type |
request_throttle_rpm |
integer, numeric string, or null | No | Maximum target requests per minute, from 1 through 600 |
custom_goal_prompt |
string or null | No | Attack focus; maximum 8,000 characters |
For API targets, target_url contains only the endpoint URL. Put request
payload examples, schemas, model identifiers, and expected response shapes in
custom_goal_prompt. Headers support the same validation limits as
browser_headers on application reports.
curl https://superagent.sh/api/v1/reports/agent \
-X POST \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"target_type": "api",
"target_url": "https://openrouter.ai/api/v1/chat/completions",
"agent_type": "chatbot",
"headers": {
"Authorization": "Bearer target_api_key"
},
"custom_goal_prompt": "POST JSON with model qwen/qwen3.7-flash and a messages array. Replace the user message with each attack prompt."
}'For a browser-driven Agent report, use "target_type": "web_app" and optionally provide generated or test-account credentials:
{
"target_type": "web_app",
"target_url": "https://agent.example.com/chat",
"agent_type": "chatbot",
"login_email": "security-test@example.com",
"login_password": "secret",
"headers": {
"X-Test-Environment": "security"
}
}Response
202 Accepted
{
"data": {
"id": "report_uuid",
"object": "report",
"type": "agent",
"description": "openrouter.ai",
"agent_type": "chatbot",
"target_type": "api",
"target_url": "https://openrouter.ai/api/v1/chat/completions",
"allowed_host": "openrouter.ai",
"request_throttle_rpm": null,
"custom_goal_prompt": "POST JSON with a messages array.",
"status": "in_progress",
"sandbox_status": "provisioning",
"agent_status": "pending",
"created_at": "2026-07-31T12:00:00.000Z",
"updated_at": "2026-07-31T12:00:00.000Z"
}
}Credentials and target headers are encrypted at rest and never returned. Agent
reports created through REST or MCP are marked with the API creation type in
the dashboard; reports created in the dashboard are marked Manual.
Start a Package run
POST /api/v1/reports/package starts a black-box assessment against installable software. Superagent follows your installation instructions in an isolated sandbox, then tries to breach the installed package.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
installation_instructions |
string | Yes | How to install and start the package; maximum 16,000 characters |
custom_goal_prompt |
string or null | No | Attack focus; maximum 8,000 characters |
curl https://superagent.sh/api/v1/reports/package \
-X POST \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"installation_instructions": "brew install foo",
"custom_goal_prompt": "Focus on privilege escalation via local sockets"
}'Response (202 Accepted)
{
"data": {
"id": "report_uuid",
"object": "report",
"type": "package",
"installation_instructions": "brew install foo",
"custom_goal_prompt": "Focus on privilege escalation via local sockets",
"status": "in_progress",
"sandbox_status": "provisioning",
"agent_status": "pending",
"created_at": "2026-08-10T12:00:00.000Z",
"updated_at": "2026-08-10T12:00:00.000Z"
}
}Package report lifecycle webhooks are not currently emitted; poll the report endpoint for progress.
Track report lifecycle
Report creation is asynchronous. Poll GET /api/v1/reports/{report_id} for every report type. Repository and standalone application reports can also publish:
report.startedto receive the report object after it is created and accepted for provisioning.report.finishedto receive the final agent outcome when the report enters review or fails.
Use the webhook event id for idempotency. A successful report.finished event normally has status: "in_review", agent_status: "completed" or "review", and outcome: "succeeded". Failed provisioning or execution returns outcome: "failed" with safe error context.
Agent and Package report lifecycle webhooks are not currently emitted; poll the report endpoint for progress.
See the Webhooks guide for payloads, signatures, retries, and event subscriptions.
Errors
Report endpoints can return:
| HTTP status | Code | Meaning |
|---|---|---|
400 |
invalid_request |
Invalid JSON, URL, repository, query parameter, or request field |
401 |
unauthorized |
Missing or invalid API key |
404 |
not_found |
Report does not exist, or the repository is not connected to the organization |
409 |
conflict |
Report scan has not finished successfully, or became ineligible before the review update was saved |
500 |
internal_error |
Unexpected server failure |
Next steps
- Manage findings with the Findings API
- Configure Red Teaming
- Subscribe to report events with Webhooks
Attack scenarios
List the category's built-in scenarios (16 for web_app, 15 each for agent and repository) and your organization's saved scenarios with GET /api/v1/attack-scenarios?category=agent, web_app, or repository. POST /api/v1/attack-scenarios accepts a complete non-secret definition copied from that list. Use a custom- prefixed ID for a new copy. To edit, send the saved ID and current revision; the response contains a new immutable revision. A stale edit returns 409.
Repository, Application and Agent report creation accepts an optional selection:
{ "attack_scenario": { "id": "APP-03", "revision": 1 } }Use the ID for the matching report category. Omit the field or pass null for General assessment. Without a revision, the current definition is resolved when the run is created. The report response includes its resolved attack_scenario; report retrieval also includes per-peer scenario_coverage for the current attempt. A rerun retains the original definition and starts fresh coverage. Saved asset settings pin their revision for subsequent manual and scheduled runs.
MCP exposes the same catalog through list_attack_scenarios, revisions through save_attack_scenario, and selection through create_repository_report, create_web_app_report and create_agent_report. Scenario selection changes focus without expanding hosts, supported drivers or action permissions. Secrets belong in encrypted credentials, never saved definitions. Coverage states and versioned control relationships do not establish full compliance.
Image validation reports
Use POST /reports/image with a version_id, UUID idempotency_key, optional
candidate_version_id, and optional target_keys. List them using
GET /reports?type=image, optionally filtered by image_id, and retrieve details
using GET /reports/{report_id}. Image execution statuses are queued,
provisioning, running, completed, failed, and cancelled; completed means
the assessment finished, with exposure and fix outcomes in result. Image reports
have no separate review status.
Image reports additionally support GET /reports/{report_id}/events,
POST /reports/{report_id}/cancel, and DELETE /reports/{report_id}. These
operations preserve the existing cancellation fencing, sandbox cleanup, billing,
and webhook behavior. See Images API for complete examples.