List, retrieve, and create repository, Web app, and Agent security reports with organization API keys. Creation endpoints start billable work and return 202 Accepted while sandbox provisioning continues.

All requests require the Bearer authentication described in the API overview.

List reports

GET /api/v1/reports returns repository, Web app, and Agent 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

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

Create a repository report

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.

Create a Web app report

POST /api/v1/reports/web-app starts a report 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.

Create an Agent report

POST /api/v1/reports/agent starts adversarial testing against an AI agent through either a Web app 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 Web app 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 Web app targets
login_password	string or null	No	Login password for Web app targets
headers	object or null	No	Encrypted HTTP headers sent to either target modality
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 Web app 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.

Create a Package report

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 Web app 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 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

• Findings API
• MCP server
• Webhooks