API Quickstart¶

This guide walks through the shortest path to creating and tracking a pentest session through the Integration API.

Warning

The Integration API is currently in beta and is only available to Team and Enterprise subscribers.

What you need¶

A Vulnetic account with available account balance
A Team or Enterprise subscription with beta API access enabled
An issued integration credential
Scopes that allow project and session operations

The examples below use the current beta base URL:

https://app.vulnetic.ai/api/v1
<AUTH_HEADER_NAME>
YOUR_API_CREDENTIAL

Step 1: Verify the integration identity¶

curl -sS "https://app.vulnetic.ai/api/v1/me" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL"

Example response:

{
  "account_id": "4f0d0a7d-644d-4dad-b5a4-c8f455e6f6b8",
  "api_client_id": "d4c8f636-5fcd-486f-8b47-3f254eb5ac25",
  "client_name": "Acme Security Automation",
  "delegated_user_id": "ea0580a8-8df4-43f1-b28e-87f1dc1b3a90",
  "roles": ["integration"],
  "scopes": [
    "projects:read",
    "projects:write",
    "sessions:read",
    "sessions:write"
  ]
}

Step 2: Create a project¶

curl -sS -X POST "https://app.vulnetic.ai/api/v1/projects" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production",
    "project_metadata": {
      "environment": "production",
      "owner": "security-team"
    }
  }'

Example response:

{
  "id": "11111111-1111-1111-1111-111111111111",
  "account_id": "4f0d0a7d-644d-4dad-b5a4-c8f455e6f6b8",
  "name": "Acme Production",
  "project_metadata": {
    "environment": "production",
    "owner": "security-team"
  },
  "session_count": 0,
  "created_by_user_id": "ea0580a8-8df4-43f1-b28e-87f1dc1b3a90",
  "created_at": "2026-04-13T18:00:00Z",
  "updated_at": "2026-04-13T18:00:00Z"
}

Step 3: Create a pentest 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"
  }'

Example response:

{
  "id": "22222222-2222-2222-2222-222222222222",
  "account_id": "4f0d0a7d-644d-4dad-b5a4-c8f455e6f6b8",
  "address": "https://app.example.com",
  "status": "halted",
  "project_id": "11111111-1111-1111-1111-111111111111",
  "methodology_id": null,
  "created_at": "2026-04-13T18:05:00Z",
  "updated_at": "2026-04-13T18:05:00Z",
  "active_duration_seconds": 0,
  "session_time_limit_seconds": 14400,
  "session_type": "pentest",
  "scope": "Authenticated production web application test."
}

Step 4: Optional session lifecycle control¶

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 API reference exposes a session status endpoint, but direct execution control may not be enabled for every integration workflow. Treat project creation, session creation, polling, findings, and documents as the guaranteed integration surface unless Vulnetic has explicitly enabled lifecycle control for your integration.

Step 5: Poll the session¶

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

Step 6: Inspect execution events¶

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

Step 7: Review findings¶

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

Step 8: Create a note document¶

curl -sS -X POST "https://app.vulnetic.ai/api/v1/documents" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme test notes",
    "description": "Operator notes for the production assessment",
    "content": {
      "summary": "Initial validation complete"
    }
  }'

Next¶

Authentication: identity and scopes
Sessions: full session lifecycle
Findings: updates and transitions