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.

Session status endpoint¶

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, but direct execution control may not be enabled for every integration workflow. Use this endpoint only if Vulnetic has explicitly enabled lifecycle control for your integration.

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
}