Sessions¶

Sessions are the core execution unit for pentest work.

Endpoints¶

GET /api/v1/sessions
POST /api/v1/sessions
GET /api/v1/sessions/{session_id}
PATCH /api/v1/sessions/{session_id}
GET /api/v1/sessions/{session_id}/events
PATCH /api/v1/sessions/{session_id}/status
PATCH /api/v1/sessions/{session_id}/project

Session lifecycle¶

The documented statuses are:

halted
queued
active
active_auto
complete
failed

Create a session¶

curl -sS -X POST "https://app.vulnetic.ai/api/v1/sessions" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "https://app.example.com",
    "scope": "Authenticated production web application test.",
    "project_id": "11111111-1111-1111-1111-111111111111",
    "session_time_limit_seconds": 14400,
    "allow_automatic_task_creation": true,
    "session_type": "pentest"
  }'

The create endpoint is described as creating a new halted session.

Start a pentest¶

curl -sS -X PATCH "https://app.vulnetic.ai/api/v1/sessions/22222222-2222-2222-2222-222222222222/status" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active_auto"
  }'

Note

The contract exposes create-session and update-status primitives separately. That means the natural way to start execution is: create a halted session, then transition it to active or active_auto.

List sessions¶

curl -sS "https://app.vulnetic.ai/api/v1/sessions?project_id=11111111-1111-1111-1111-111111111111&status=active_auto&include_total=false" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL"

Update session details¶

curl -sS -X PATCH "https://app.vulnetic.ai/api/v1/sessions/22222222-2222-2222-2222-222222222222" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "Authenticated production web application and admin console test.",
    "session_time_limit_seconds": 21600
  }'

Assign a session to a project¶

curl -sS -X PATCH "https://app.vulnetic.ai/api/v1/sessions/22222222-2222-2222-2222-222222222222/project" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "11111111-1111-1111-1111-111111111111"
  }'

Read session events¶

curl -sS "https://app.vulnetic.ai/api/v1/sessions/22222222-2222-2222-2222-222222222222/events" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL"

Example event item:

{
  "id": 1042,
  "session_id": "22222222-2222-2222-2222-222222222222",
  "task": "Enumerate authenticated routes",
  "short_task": "Route enumeration",
  "command": "ffuf -w routes.txt -u https://app.example.com/FUZZ",
  "output": "...",
  "annotations": {
    "tags": ["recon"]
  },
  "analysis": "Potential admin route discovered",
  "created_at": "2026-04-13T18:16:00Z",
  "updated_at": "2026-04-13T18:16:03Z",
  "parent_id": null,
  "validate_finding_id": null,
  "status": "complete",
  "position": 14
}