Investigations API

Use /api/v2/investigations for managed investigations. Authentication, capture permissions, provider eligibility, privacy and workflow validation remain server-side. The CLI is a client of this API.

Submit a configuration

Exchange the long-lived API key for a short-lived access token first. This example uses jq to extract the token:

SERVER=http://127.0.0.1:8080
ACCESS_TOKEN="$(curl --fail-with-body --silent --show-error \
  -X POST "$SERVER/api/v2/api-access/token" \
  -H "Authorization: Bearer $PACKETSAFARI_API_KEY" | jq -r '.data.accessToken')"
test -n "$ACCESS_TOKEN" && test "$ACCESS_TOKEN" != null

Do not send the API key itself to ordinary capture or investigation endpoints. Replace CAPTURE_ID below with an uploaded capture ID:

curl --fail-with-body --silent --show-error \
  "$SERVER/api/v2/investigations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "capture_id": "CAPTURE_ID",
    "idempotency_key": "incident-4821-security-first",
    "goal": "security",
    "workflow": "fast",
    "ai": {"model": "gpt-5.6-luna", "reasoning_effort": "low"},
    "evidence": {},
    "security": {"full_ids_scan_requested": false},
    "privacy": {"enabled": false},
    "delivery": {"email_report_requested": false}
  }'

Use a unique idempotency key for a new request; reuse it only for retries of the same request/settings. The returned receipt provides the investigation identity. Do not assume HTTP acceptance means the report is ready.

Discover a permitted connection and model

Using the short-lived token from above, list available source IDs:

curl --fail-with-body --silent --show-error \
  "$SERVER/api/v2/investigations/options" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Read sources[].id and organizationId from that response. To inspect one source's models, substitute its ID and the API key's team ID:

curl --fail-with-body --silent --show-error --get \
  "$SERVER/api/v2/investigations/options" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'authSourceId=YOUR_AI_CONNECTION_ID' \
  --data-urlencode 'organizationId=YOUR_TEAM_ID'

For a personal source without a team scope, omit organizationId. Team API keys must use their own returned team ID when querying a source. The catalog reports models[].id, eligibleStages, supportedReasoningEfforts, and defaultReasoningEffort. Discovery does not execute a model call or grant access. Save the selected source ID as CLI ai-auth-source-id, or set ai.ai_auth_source_id in an investigation request. Only omit reasoning when you intend the applicable server/model default; explicit settings take precedence.

Upload a local PCAP

For a small direct upload, preserve the local filename in the multipart file part:

PCAP="$HOME/Desktop/incident/capture.pcap"
UPLOAD_JSON="$(curl --fail-with-body --silent --show-error \
  "$SERVER/api/v2/upload/pcap" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@$PCAP" \
  -F 'tags=[]' \
  -F 'wanthelp=false' \
  -F 'anonymize=false')"
CAPTURE_ID="$(printf '%s' "$UPLOAD_JSON" | jq -r '.data.id // .data.pcapid // .id // .pcapid')"
printf 'Capture: %s\n' "$CAPTURE_ID"

The deployment may require chunked upload for larger files. Use packetsafari investigate or packetsafari ingest when you want duplicate detection, resumable chunks, progress, and retry state instead of implementing that protocol yourself.

Endpoints

Poll the returned job identity rather than repeatedly submitting. The CLI manages streaming, reconnect, and export rendering for terminal users.

Configuration groups

goal, workflow, evidence, security, privacy, ai, and delivery describe the request. Optional alert context specializes it for IDS verification. API goals use root_cause, security, wifi_performance_path, summary, network_responsibility, custom, or alert; the CLI accepts friendlier aliases such as troubleshoot and wifi.

Workflows are fast, progressive, triage_deep, and triage. The CLI's --verify convenience submits Fast and subsequently requests independent verification; it is not a fifth API workflow value.

Privacy preparation

With server-side anonymization, upload the original, start the existing Anoncap operation, and wait for its protected capture. Submit that protected ID with privacy.enabled: true, privacy.source_capture_id, and the matching privacy.options. The server checks preparation completion, lineage, and policy. The general investigation endpoint does not itself start Anoncap.

Use the CLI privacy workflow if you want it to manage preparation and waiting. Do not submit the original as though it were the protected output.

Existing alert endpoints remain compatibility adapters. For new integrations, use the general investigation contract rather than building another submission workflow around the low-level Agent run endpoint.