Skip to content

API Quickstart

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

Warning

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

What you need

  • A Vulnetic account with available account balance
  • A Pro 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 halted 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: Start the 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 current contract clearly supports creating a halted session and updating session status. Starting a pentest by transitioning the session to active or active_auto is the intended workflow inferred from those documented primitives.

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