Skip to content

API overview

The Revelion API lets you start missions and follow them from your own systems, such as a CI pipeline or a scheduler. It's a JSON API over HTTPS, authenticated with API keys.

Base URL

https://api.revelion.ai/v1

Availability

API access depends on your organisation's plan. If your plan doesn't include it, requests are refused with 403 and a message that says so. Settings → Membership in the app shows your plan.

Quick start

1. Create an API key

In the app, open Settings → API and select Create Key. Name the key, give it the write permission, and create it. The key is displayed only once, so copy it straight away.

Make it available as REVELION_API_KEY in the shell you'll use:

Terminal
export REVELION_API_KEY="YOUR_API_KEY"
Windows PowerShell
$env:REVELION_API_KEY = "YOUR_API_KEY"

In automated systems, load the key from your secret store instead of typing it.

2. Start a mission

Send POST /scans with a target and your confirmation that you're authorised to test it. Replace the example target with a system you're authorised to test.

Terminal
IDEMPOTENCY_KEY="$(uuidgen)"

curl https://api.revelion.ai/v1/scans \
  -H "Authorization: Bearer $REVELION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "name": "Staging web app",
    "target": {"type": "url", "url": "https://app.example.invalid"},
    "scan_mode": "quick",
    "authorization_confirmed": true
  }'

If uuidgen isn't installed, use any unique value that meets the rules in Retries and idempotency.

Windows PowerShell
$idempotencyKey = [guid]::NewGuid().ToString()

$body = @{
    name                    = "Staging web app"
    target                  = @{ type = "url"; url = "https://app.example.invalid" }
    scan_mode               = "quick"
    authorization_confirmed = $true
} | ConvertTo-Json -Depth 5

$request = @{
    Method      = "Post"
    Uri         = "https://api.revelion.ai/v1/scans"
    Headers     = @{
        Authorization     = "Bearer $env:REVELION_API_KEY"
        "Idempotency-Key" = $idempotencyKey
    }
    ContentType = "application/json"
    Body        = $body
}
$mission = Invoke-RestMethod @request
$mission.id
Python
import os
import uuid

import requests

API = "https://api.revelion.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['REVELION_API_KEY']}"}

idempotency_key = str(uuid.uuid4())

response = requests.post(
    f"{API}/scans",
    headers={**HEADERS, "Idempotency-Key": idempotency_key},
    json={
        "name": "Staging web app",
        "target": {"type": "url", "url": "https://app.example.invalid"},
        "scan_mode": "quick",
        "authorization_confirmed": True,
    },
    timeout=30,
)
response.raise_for_status()
mission = response.json()
print(mission["id"], mission["status"])

Set authorization_confirmed only when it's true

authorization_confirmed: true is your organisation's confirmation that it's authorised to test every target in the request, and Revelion records it with the mission. Without it, the API won't start the mission.

The API replies 202 Accepted with the new mission. Keep its id:

Response (abridged)
{
  "id": "4f1c2b7e-8d3a-4c55-9e21-6a0b3f9d2c18",
  "name": "Staging web app",
  "status": "pending",
  "target": {"type": "url", "url": "https://app.example.invalid"},
  "scan_mode": "quick",
  "scan_type": "web"
}

3. Check its status

Terminal
curl https://api.revelion.ai/v1/scans/MISSION_ID \
  -H "Authorization: Bearer $REVELION_API_KEY"
Windows PowerShell
$headers = @{ Authorization = "Bearer $env:REVELION_API_KEY" }
Invoke-RestMethod -Uri "https://api.revelion.ai/v1/scans/MISSION_ID" -Headers $headers
Python
# Continues from the previous example.
import time

FINAL = {"completed", "error", "cancelled"}

while mission["status"] not in FINAL:
    time.sleep(30)
    response = requests.get(f"{API}/scans/{mission['id']}", headers=HEADERS, timeout=30)
    response.raise_for_status()
    mission = response.json()

print(mission["status"], mission.get("error_message"))

A mission ends as completed, error or cancelled. Until then it's pending or running, or paused, which can be resumed. Checking every 30 seconds or so is plenty.

Retries and idempotency

Starting a mission uses credits, so a retry must not start a second one by accident. Send an Idempotency-Key header when you create a mission:

  • Generate the key once for each mission you mean to start: any string of 8 to 255 letters, digits and ._:~+-. A UUID works well.
  • If the request fails or times out, send the same request again with the same key. Keys are remembered for 24 hours.
  • If the first request succeeded, you get its original response instead of a new mission, marked with the header Idempotent-Replay: true.
  • If the first request is still being processed, you get 409; wait briefly and retry.
  • Reusing a key with a different request body is refused with 409.
  • If the first request failed, the key is released, and your retry is handled as a new request.

Without a key, a retry starts a second mission, and you're charged for both.

Errors

Errors share one shape:

Error
{
  "error": {
    "type": "forbidden",
    "code": 403,
    "message": "API key missing required scope: write"
  }
}

type is stable, so branch on it rather than on message.

Status type Meaning Retry?
400 invalid_request A value isn't acceptable, such as an unsupported target type No. Fix the request.
401 authentication_error The API key is missing or isn't recognised No
402 payment_required Not enough credits to start a mission After adding credits
403 forbidden Not permitted: see the message No
404 not_found Nothing with that ID in your organisation No
409 conflict An idempotency conflict, or the mission's state doesn't allow the action Only if the message says to
411 length_required The request body was sent without a Content-Length header With the header
413 payload_too_large The request body is larger than 1 MB No
422 validation_error The body doesn't match the expected shape No. Fix the request.
429 rate_limit_exceeded Too many requests Yes, after Retry-After seconds
503 api_error Temporarily unavailable Yes, shortly

Every response carries an X-Request-Id header. Include it when you report a problem.

Responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the time the current window resets, in Unix seconds.

Pagination

Lists take limit and offset query parameters and return:

List response
{
  "data": [],
  "has_more": false,
  "limit": 20,
  "offset": 0
}

Full reference

The API serves its complete reference, covering every endpoint including findings, assets, reports, usage and webhooks, at api.revelion.ai/v1/docs. A machine-readable version is at api.revelion.ai/v1/openapi.json.