Create repository and Web app security reports with organization API keys. Both endpoints start billable work and return 202 Accepted while sandbox provisioning continues.

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

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.

Track report lifecycle

Report creation is asynchronous. Subscribe a webhook target to:

• 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.

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, or request field
401	unauthorized	Missing or invalid API key
404	not_found	Repository is not connected to the organization
500	internal_error	Unexpected server failure

Next steps

• Findings API
• Webhooks