Pentests API

HTTP reference for pentest CRUD, assets, agents, phases, lifecycle, comments, and the run/report operations on the streaming backend.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). Run, stream, report and cancel operations live on the streaming backend at https://aleex.aleex-rank.ai and are flagged as such below.

Pentest model

A pentest has a fixed type (web, api, server) and mode (guided, automatic), a status from its lifecycle, one or more assets, and agents assigned across phases 1 Reconnaissance, 2 Enumeration, 3 Analysis. See Pentests, assets & phases.

List pentests

GET /pentests

Query parameters: page (default 1), per_page (default 20), status, type.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 15,
        "name": "Acme web assessment",
        "type": "web",
        "mode": "guided",
        "status": "configured",
        "progress_percentage": 0,
        "created_at": "2026-01-29 14:30:00"
      }
    ],
    "pagination": {"total": 1, "count": 1, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

Create a pentest

POST /pentests
Content-Type: application/json

Field	Type	Required	Notes
`name`	string	Yes	Display name
`description`	string	No	Free text
`type`	string	Yes	`web`, `api` or `server`
`mode`	string	Yes	`guided` or `automatic`
`url`	string	No	Primary URL convenience field
`methodology_id`	int	Conditional	Required in guided mode; forced to `1` in automatic
`team_id`	int	Conditional	Required if you belong to any team
`assets`	array	Yes	At least one; exactly one `is_primary: true`

{
  "name": "Acme web assessment",
  "description": "Security review of the customer portal",
  "type": "web",
  "mode": "guided",
  "methodology_id": 1,
  "team_id": 4,
  "assets": [
    {"asset_type": "domain", "asset_value": "acme.example.com", "is_primary": true},
    {"asset_type": "ip", "asset_value": "192.0.2.10"},
    {"asset_type": "url", "asset_value": "https://acme.example.com/api"}
  ]
}

Response 201:

{
  "success": true,
  "data": {
    "id": 15,
    "name": "Acme web assessment",
    "type": "web",
    "mode": "guided",
    "status": "draft",
    "methodology_id": 1,
    "methodology_name": "OWASP Top 10",
    "team": {"id": 4, "name": "Security Team"},
    "assets": [
      {"id": 1, "type": "domain", "value": "acme.example.com", "is_primary": true},
      {"id": 2, "type": "ip", "value": "192.0.2.10", "is_primary": false},
      {"id": 3, "type": "url", "value": "https://acme.example.com/api", "is_primary": false}
    ],
    "created_at": "2026-01-29 14:30:00"
  }
}

Retrieve, update, delete

GET    /pentests/{id}
PATCH  /pentests/{id}
DELETE /pentests/{id}

GET returns the pentest with its assets and agents. PATCH (or PUT) updates mutable fields such as name and description. DELETE soft-deletes the pentest.

Limits and quality gate

GET /pentests/limits
GET /pentests/quality-gate

limits reports how many pentests you may still create this period for your tier. quality-gate evaluates a rolling quality check over your last 7 pentests.

{
  "success": true,
  "data": {
    "max_pentests_per_month": 50,
    "used_this_month": 12,
    "remaining": 38
  }
}

Response fields above are representative; consult the live response for exact keys.

Methodologies

GET /methodologies

Lists the methodologies you can attach to a guided pentest.

{
  "success": true,
  "data": [
    {"id": 1, "name": "OWASP Top 10", "description": "Web application security testing"},
    {"id": 2, "name": "PTES", "description": "Penetration Testing Execution Standard"}
  ]
}

Assets

GET    /pentests/{id}/assets
POST   /pentests/{id}/assets
DELETE /pentests/{id}/assets/{assetId}

Add an asset:

{"asset_type": "url", "asset_value": "https://acme.example.com/admin", "is_primary": false}

asset_type is one of url, domain, ip, api. A pentest must always keep at least one asset.

Agents

Agents are assigned per phase, 3 to 4 per phase, in order. You cannot assign phase N+1 until phase N has at least 3 agents.

GET    /pentests/{id}/agents
POST   /pentests/{id}/agents
DELETE /pentests/{id}/agents/{agentId}
POST   /pentests/{id}/agents/deactivate
GET    /pentests/{id}/default-agents

Assign agents to a phase:

{
  "agents": [
    {"agent_id": 101, "phase_id": 1, "execution_order": 1},
    {"agent_id": 102, "phase_id": 1, "execution_order": 2},
    {"agent_id": 103, "phase_id": 1, "execution_order": 3}
  ]
}

Response 201 — note that agents which can’t be assigned (duplicates, or a phase already at its max of 4) are reported rather than silently dropped:

{
  "success": true,
  "data": {
    "pentest_id": 15,
    "assigned_count": 2,
    "assigned_ids": [1, 2],
    "skipped_count": 1,
    "skipped": [
      {"agent_id": 103, "phase_id": 1, "reason": "already_assigned"}
    ]
  }
}

GET /pentests/{id}/default-agents returns the default agents grouped by phase. For an automatic pentest that is still configured with no agents yet, this call also auto-assigns those defaults and reports auto_assigned: true. DELETE …/agents/{agentId} unassigns one agent (refused if it would drop a phase below 3); POST …/agents/deactivate clears all assignments.

Phases and lifecycle

A pentest moves draft → configured → running → phase_completed → processing → completed, with paused, cancelled, archived and failed as off-ramps. Only valid transitions are accepted.

Mark a phase complete (user-facing):

POST /pentests/{id}/phases/{phaseId}/complete

Finish the pentest:

POST /pentests/{id}/finish

The pentest must be in phase_completed or processing — you cannot finish a running pentest. A guided pentest must also have at least one processed vulnerability first; automatic pentests are finished for you by the streaming backend.

{
  "success": true,
  "data": {
    "id": 15,
    "status": "completed",
    "progress_percentage": 100,
    "total_vulnerabilities": 12,
    "end_time": "2026-01-29 16:45:00"
  }
}

Error when finished too early:

{
  "success": false,
  "error": {
    "message": "Pentest must be in 'phase_completed' or 'processing' state to finish (current: running).",
    "code": 400
  }
}

Comments and evidences

GET    /pentests/{id}/comments
POST   /pentests/{id}/comments
DELETE /pentests/{id}/comments/{commentId}
GET    /pentests/{id}/evidences

Add a comment:

{"comment": "Re-scoped to include the staging environment"}

GET /pentests/{id}/evidences returns the agent operations that produced findings, i.e. the original discovery evidence across the pentest.

Run, process and report (streaming backend)

These operations are served by the streaming backend at https://aleex.aleex-rank.ai, not the REST base. They authenticate with the same credentials.

POST https://aleex.aleex-rank.ai/chat
POST https://aleex.aleex-rank.ai/handle_vulnerability
POST https://aleex.aleex-rank.ai/generate_report
GET  https://aleex.aleex-rank.ai/pentest/{id}/stream
POST https://aleex.aleex-rank.ai/pentest/{id}/cancel

POST /chat launches execution and streams agent activity over Server-Sent Events.
POST /handle_vulnerability processes a guided pentest’s findings into stored vulnerabilities before you finish it.
POST /generate_report produces the PDF report for a completed pentest.
GET /pentest/{id}/stream reconnects to an in-progress run’s event stream.
POST /pentest/{id}/cancel cancels a running pentest.

Launch body:

{
  "agent_type": "pentest",
  "pentest_id": 15,
  "phase_id": 1,
  "mode": "guided",
  "user_prompt": "Start reconnaissance of the target"
}

The full request body, dispatch rules and event contract for /chat are documented in Chat & pentest execution; the event payloads are detailed in Streaming.

Vulnerabilities on a pentest

Triage endpoints live under /pentests/{id}/vulnerabilities/... and have their own page: Vulnerabilities API. Webhooks for vulnerability events are under /pentests/{id}/webhooks — see Webhooks.