Run Phantom Agent from your code.

Set two environment variables, then send one request. Investigations run in the background, so the response gives you an investigation ID and links for status and report checks.

1
2
3
4
5
6
7
8
9
10
11
12
13
export PHANTOM_AGENT_API_KEY='pa_live_...'
export PHANTOM_AGENT_API_BASE_URL='https://phantomhelix.com'

curl --fail-with-body \
  -X POST "$PHANTOM_AGENT_API_BASE_URL/api/v1/phantom-agent/investigations" \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: case-42-attempt-1' \
  --data '{
    "query": "Investigate the ownership and public-risk signals for Example Company.",
    "max_credits": 100,
    "client_reference": "case-42"
  }'

Create a personal API key from your dashboard.

Send the key as a Bearer token with every request. A revoked key stops working at once, and the full key is shown only when you create it. Keep it in server-side code on a trusted server. Do not put it in browser code or a public repository.

1
Authorization: Bearer pa_live_...

Send a focused research question and the most Credits you approve for the run. The optional client reference can link the investigation to a record in your system.

1
2
3
4
5
{
  "query": "Investigate the ownership and public-risk signals for Example Company.",
  "max_credits": 100,
  "client_reference": "case-42"
}

Give each create attempt an idempotency key. If a network request has an unclear result, retry the same body with the same key. This prevents duplicate work and duplicate Credit use.

1
2
3
4
5
6
7
8
{
  "id": "inv_...",
  "status": "queued",
  "client_reference": "case-42",
  "status_url": "/api/v1/phantom-agent/investigations/inv_...",
  "report_url": "/api/v1/phantom-agent/investigations/inv_.../report",
  "created_at": "2026-09-25T12:00:00.000Z"
}

Poll this endpoint until the status is completed, failed, or cancelled. Status can be queued, starting, running, completed, failed, or cancelled. The response also includes available timestamps.

1
2
3
4
5
export INVESTIGATION_ID='inv_...'

curl --fail-with-body \
  "$PHANTOM_AGENT_API_BASE_URL/api/v1/phantom-agent/investigations/$INVESTIGATION_ID" \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_KEY"

Request the report after the investigation is complete. The response includes structured sections, Markdown, citations, gaps, and warnings. If research is still active, the API returns REPORT_NOT_READY with Retry-After. Wait for that delay before the next request.

1
2
3
curl --fail-with-body \
  "$PHANTOM_AGENT_API_BASE_URL/api/v1/phantom-agent/investigations/$INVESTIGATION_ID/report" \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_KEY"

Read your available and reserved Credits before you start a run. This endpoint does not buy or add Credits.

1
2
3
curl --fail-with-body \
  "$PHANTOM_AGENT_API_BASE_URL/api/v1/phantom-agent/credits" \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_KEY"

Errors use one JSON shape and a stable code. Branch on error.code instead of the message, and keep X-Request-Id when you contact support.

1
2
3
4
5
6
7
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "There are not enough available Credits for this request.",
    "request_id": "req_..."
  }
}

Retry only temporary errors. Follow Retry-After when it is present, and use a bounded delay when it is not.

Retry after a delay: REQUEST_IN_PROGRESS, RATE_LIMITED, REPORT_NOT_READY, DEPENDENCY_UNAVAILABLE, and CONCURRENCY_LIMIT_REACHED.

Fix the condition first: INVALID_REQUEST, INVALID_API_KEY, ACCESS_REQUIRED, INSUFFICIENT_CREDITS, IDEMPOTENCY_CONFLICT, and REPORT_UNAVAILABLE.