> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Start repository, application, Agent, Package, and Image validation runs, then retrieve their red-team reports through the REST API.

# Reports

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](https://www.superagent.sh/docs/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` |

```bash
curl "https://superagent.sh/api/v1/reports?type=repository&status=done&limit=2" \
  -H "Authorization: Bearer sk_live_..."
```

### Response

```json
{
  "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.

```bash
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 |

```bash
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](https://www.superagent.sh/docs/api/findings) 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 |

```bash
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`

```json
{
  "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.

```bash
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`

```json
{
  "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.

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

```json
{
  "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`

```json
{
  "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 |

```bash
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`)

```json
{
  "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.started` to receive the report object after it is created and accepted for provisioning.
- `report.finished` to 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](https://www.superagent.sh/docs/webhooks) 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](https://www.superagent.sh/docs/api/findings)
- [Configure Red Teaming](https://www.superagent.sh/docs/products/red-teaming)
- [Subscribe to report events with Webhooks](https://www.superagent.sh/docs/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:

```json
{ "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](https://www.superagent.sh/docs/api/images) for complete examples.

---
Source: https://www.superagent.sh/docs/api/reports
Index: https://www.superagent.sh/llms.txt
