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:
export REVELION_API_KEY="YOUR_API_KEY"
$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.
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.
$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
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:
{
"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¶
curl https://api.revelion.ai/v1/scans/MISSION_ID \
-H "Authorization: Bearer $REVELION_API_KEY"
$headers = @{ Authorization = "Bearer $env:REVELION_API_KEY" }
Invoke-RestMethod -Uri "https://api.revelion.ai/v1/scans/MISSION_ID" -Headers $headers
# 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": {
"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:
{
"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.