API Reference

Rate limits

Per-key limits, how they are signaled, and how to handle 429s correctly.

WASViking^® applies rate limits per API key. Limits are sized for normal operational use and are documented per endpoint class.

Default limits

Endpoint class	Limit
Read endpoints (`GET`)	600 requests per minute.
Write endpoints (non-scan)	60 requests per minute.
Trigger scans	12 concurrent scans per organization.
SBOM submit	60 submissions per minute.
Secrets submit	60 submissions per minute.
Webhook test deliveries	10 per minute per webhook.

Headers

Every response includes:

Header	Meaning
`X-RateLimit-Limit`	Limit for this endpoint class.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Seconds until the window resets.

When throttled:

Status	Header	Meaning
`429`	`Retry-After: 30`	Wait at least 30 seconds before retrying.

Handling 429 correctly

Respect Retry-After. Do not retry sooner.
Use exponential backoff with jitter on repeated 429s.
Cache idempotent read responses where you can.
Coalesce. Most consumers issue many small reads that could be one paginated query.

A reasonable retry policy in pseudocode:

delay = float(headers.get("Retry-After", 30))
for attempt in range(5):
    sleep(delay + random.uniform(0, 0.5 * delay))
    response = call_api()
    if response.status_code != 429:
        return response
    delay *= 2
raise RetryExceeded()

Concurrency caps

The 12 concurrent scans cap is per organization, not per key. If you run multiple CI pipelines against the same org, plan for it. The portal shows current concurrency under Settings → API Usage.

When the cap is hit and you call POST /scans, the API:

Waits up to 60 seconds for a slot to open.
If a slot opens, accepts the scan and returns 201 Created.
If no slot opens, returns 429 with Retry-After.

In sentinel ci, this surfaces as exit code 77 (scan_capacity).

Monthly metering

Some plans meter:

AI recommendations per month.
Scans per month.
SBOM submissions per month.
Posture Share creations per month.

When the meter is exhausted on a metered scope, the API returns 403 with error: "metered". The portal shows the current meter state under Settings → API Usage and Billing → Usage.

sentinel ci surfaces this as exit code 78.

Raising your limits

Limits can be raised per organization for sustained operational need. Open a request from Settings → API Usage → Request increase or email [email protected]. Include:

The endpoint class and the new target.
Peak QPS and average QPS you expect.
A short justification.

We approve increases that match real usage. We refuse blanket "remove all limits" requests.

What the limits are NOT

They are not a hard quota on the organization (other than monthly metering, which is explicit).
They are not per-user; they are per-key.
They are not enforced at the edge separate from the application. The WASViking application stack enforces them; the Cloudflare edge runs a separate, much larger floor against abuse for public endpoints.