Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

API token obtained from the Tokens endpoint or CLI device login. Include as Authorization: Bearer <token>. Requests made with a managed CLI session also include X-Strix-Workspace: <organization_id> to pin a process to the workspace it started in; recovery endpoints report the current workspace after a concurrent switch.

Scopes

scans:write

Body

application/json

At least one target (domain_ids, repository_ids, upload_ids, or internal_targets) should be provided.

cloud_connection_ids
string[]

Cloud connections this run may read. If you omit this field, the run uses the connections that apply to its targets. A connection with empty applies_to_domain_ids and applies_to_repository_ids applies to every run. A connection with values in those lists applies only to a run that targets one of the listed domains or repositories. Send an empty array for no cloud connections.

concerns
string

Free-text security concerns to prioritize, for example IDOR on the invoices API.

connector_id
string

ID of a network connector that gives the agent access to a private network. Use listConnectors to find it.

context
string

Free-text background about the target that helps the agent, for example architecture notes or recent changes.

credentials
object[]

Test accounts the agent logs in with during the scan. Stored encrypted and never returned. Prefer saved test users where available.

domain_ids
string<uuid>[]

UUIDs of verified domains to test. Use listDomains to find them.

domain_paths
object

Map of domain ID to specific paths to scan.

engagement_type
enum<string>

Which engagement type this run is. When omitted, source-only scopes infer code_review, domain scopes infer live_test, and internal targets infer internal_infra.

Available options:
code_review,
live_test,
internal_infra,
compliance_pentest
focus
string

Free-text areas of the target to test first, for example the checkout flow.

headers
object[]

Custom HTTP headers the agent sends on every request, for example an API key header. Stored encrypted and never returned.

internal_targets
string[]

Hosts or URLs inside a private network to test through the connector, for example http://10.0.0.5:8080.

knowledge_resource_pins
object[]

Provider resources selected for this run in addition to organization-wide pins.

Maximum array length: 100
max_budget_usd
number

Self-hosted only: stop the pentest gracefully once total LLM spend reaches this amount (USD). Omit for no limit. Spend is counted from the model config's Pricing when it is set. Otherwise it uses the cost the provider reports, or the LiteLLM price table.

Required range: x <= 1000000
budget_policy
enum<string>

Self-hosted only: what happens when max_budget_usd is reached. pause parks every agent before its next model call until an operator resumes the scan with a higher limit or stops it (see POST /scans/{scanId}/budget); a paused scan waits with no deadline. stop ends the run at the limit. Defaults to pause. Ignored without max_budget_usd.

Available options:
stop,
pause
model_config_id
string<uuid>

Self-hosted installs and hosted organizations on their own LLM keys: run the scan with a named model config from Settings → LLM Models instead of the default assignment.

notification_emails
string<email>[]

Extra addresses to CC on the completion email. Validated only when notify_on_completion is true.

notify_on_completion
boolean

Email the scan creator when the pentest finishes.

org_knowledge_enabled
boolean

When true, the agent uses the organization knowledge base during the scan.

repository_branches
object

Map of repository ID to branch name.

repository_ids
string<uuid>[]

UUIDs of connected repositories to test. Use listRepositories to find them.

test_user_ids
string<uuid>[]

Saved test users attach to domain targets they cover or to internal_infra scans on the same network.

title
string

Custom scan title. When you set a title, the server does not generate one. The server trims the value.

Maximum string length: 120
upload_ids
string[]

Completed upload IDs to attach. A repository upload can be the sole target of a code review or provide white-box context for a domain pentest.

Response

The draft is ready for human review. No scan has started.

id
string<uuid>
required

Scan draft identifier.

launch_url
string<uri>
required

Give this link to the human who will review and launch the scan.

expires_at
string<date-time>
required

The time when the draft expires.