REST API

Base URL, authentication, the standard response envelope, errors, pagination and rate limits for the Rank REST API — plus where each domain lives.

Base URL

All REST endpoints live under a single versioned base URL:

https://api.aleex-rank.ai/api/v2

Every path in this reference is relative to that base. So GET /pentests means GET https://api.aleex-rank.ai/api/v2/pentests.

Run and stream operations — launching a pentest, streaming live agent activity, reconnecting to or cancelling an in-progress run, generating a report — are not served from this base. They are handled by the streaming backend at https://aleex.aleex-rank.ai over Server-Sent Events. Those endpoints are documented in Chat & pentest execution (and, from the SDK’s perspective, in Streaming); everything else is here.

Authentication

The API accepts two credential types, and each has its own header. The gateway is strict about which goes where:

For programmatic access you almost always want an API token in the X-API-Key header:

GET /api/v2/pentests HTTP/1.1
Host: api.aleex-rank.ai
X-API-Key: rk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl https://api.aleex-rank.ai/api/v2/pentests \
  -H "X-API-Key: rk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A few details that matter in practice:

• Tokens are prefixed rk_ followed by 40 alphanumeric characters. Legacy tokens with a SCYTALE_ prefix are also accepted in the X-API-Key header.
• The Authorization: Bearer header is reserved for JWTs (the web session). Sending an API token there is rejected — put API tokens in X-API-Key.
• If no valid credential is present the API responds 401 with: Use "Authorization: Bearer <jwt>" or "X-API-Key: <api_token>".
• Tokens can be scoped to a subset of permissions and teams, and counted against either your individual pool or a team’s. Creating, scoping and rotating tokens is covered in Authentication & API tokens.

The HTTP endpoints for sessions, account changes, two-factor authentication and programmatic token management are in the Authentication & account API.

Response envelope

Successful responses are wrapped in a standard envelope: a success flag and a data payload.

{
  "success": true,
  "data": {
    "id": 15,
    "name": "Acme web assessment",
    "type": "web",
    "status": "configured"
  }
}

Creation endpoints return the same shape with HTTP 201. A handful of report-style endpoints (for example a vulnerability summary) return their object directly inside data; those are noted where they occur.

Error format

Errors set the matching HTTP status and carry a success: false flag with an error object holding a human-readable message, the numeric code, and optional details.

{
  "success": false,
  "error": {
    "message": "Phase 1 requires at least 3 agents to be assigned at once",
    "code": 400,
    "details": {"phase_id": 1, "min_agents": 3, "provided": 2}
  }
}

Common statuses:

Pagination

List endpoints accept page (default 1) and per_page (default 20, capped per endpoint) query parameters and return an items array plus a pagination block inside data:

GET /api/v2/auth/api-tokens?page=1&per_page=20

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "total": 42,
      "count": 20,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 3
    }
  }
}

Some collections use meta (total, page, per_page) instead; both forms are paginated the same way.

Rate limits

Most authenticated domains are rate-limited per bucket; sustained bursts receive 429 Too Many Requests. Typical ceilings are 60 requests per 60 seconds (pentests, scheduled pentests, webhooks, integrations, evidence). Catalog reads are looser (120/60); the global findings rollup (GET /vulnerabilities/summary, GET /vulnerabilities/validation-metrics) is tighter (30/60). Pentest creation additionally requires a verified email. Quotas otherwise come from your tier (pentests per month, API tokens, agents, scheduled pentests, webhook subscriptions) and your AI usage budget rather than per-request limits — see Teams & tiers.

Launching a pentest is fail-closed: without an active Rules of Engagement the streaming backend refuses the run (409 with no_active_roe; an active kill switch is 403). Activate a RoE that covers the assets before you call /chat.

Domains