> 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, and Package Red Team runs, then retrieve their red-team reports through the REST API.

# Reports

Start repository, application, Agent, and Package Red Team 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, and Package red-team reports for the API key's organization, newest first.

### 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`, or `package` |
| `status` | string | none | Restrict results to `in_progress`, `in_review`, `done`, or `failed` |

```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, or Agent 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`.

## 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 Team 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 |
| `500` | `internal_error` | Unexpected server failure |

## Next steps

- [Manage findings with the Findings API](https://www.superagent.sh/docs/api/findings)
- [Configure Red Team](https://www.superagent.sh/docs/security-workers/red-team)
- [Subscribe to report events with Webhooks](https://www.superagent.sh/docs/webhooks)

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