Skip to content

Missions

A mission is one scoped assessment. In the API, missions live under /scans.

Create a mission

Request
POST /v1/scans

Requires the write scope. Send an Idempotency-Key header, so that a retry can't start a second mission.

Request body

Field Type Description
name string Required. A name you'll recognise in the app.
target object Required. What to test: {"type": "url", "url": "…"} for a web application, or {"type": "ip", "ip": "…"} for a host.
authorization_confirmed boolean Must be true for the mission to start. See Authorisation.
scan_mode string quick, normal or deep. Defaults to normal. Whether deep is available depends on your plan.
scan_type string web or network. Defaults to web.

Other optional fields are described in the full reference.

Request body
{
  "name": "Staging web app",
  "target": {"type": "url", "url": "https://app.example.invalid"},
  "scan_mode": "normal",
  "scan_type": "web",
  "authorization_confirmed": true
}

Authorisation

authorization_confirmed is your organisation's confirmation that it's authorised to test every target in the request. Set it to true only when that's so. Revelion records the confirmation with the mission.

The field is optional in the request schema and defaults to false, so a request can be well formed and still be refused. Without the confirmation, the API responds:

403 Forbidden
{
  "error": {
    "type": "forbidden",
    "code": 403,
    "message": "You must confirm you are authorized to perform security testing on this target before a mission can start. Send authorization_confirmed=true with this request. If you are using the dashboard, reload the page and tick the authorization box in the mission wizard."
  }
}

Response

202 Accepted, with the new mission.

Requests can also be refused for reasons the schema can't show: not enough credits (402), an option your plan doesn't include (403), or a target value that isn't acceptable (400). The error reference lists every status.

Get a mission

Request
GET /v1/scans/{id}

Requires the read scope. Returns the mission, or 404 if there's no mission with that ID in your organisation.

List missions

Request
GET /v1/scans?limit=20&offset=0&status=running

Requires the read scope. Returns missions newest first, as a paginated list.

Parameter Description
limit How many to return, up to 100. Defaults to 20.
offset How many to skip. Defaults to 0.
status Optional. Return only missions with this status.

The mission object

Field Description
id The mission's ID
name The name you gave it
status Where it is in its lifecycle
target What it's testing
scan_mode quick, normal or deep
scan_type web or network
error_message Why the mission ended in error, when it did
created_at, started_at, completed_at, updated_at Timestamps

The full reference lists every field.

Statuses

Status Meaning Final?
pending Accepted and waiting to run No
running In progress No
paused Paused; it can be resumed No
completed Finished Yes
error Ended with an error; see error_message Yes
cancelled Cancelled before it finished Yes

More mission endpoints

The full reference also covers cancelling, pausing and resuming missions, listing a mission's agents and events, and reading its findings and reports.