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
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.",
    "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. Credits are used as the investigation runs. No per-investigation spending limit is set. The investigation can use your available account Credits until it finishes, you cancel it, or further work cannot be funded. The optional client reference can link the investigation to a record in your system.

1
2
3
4
{
  "query": "Investigate the ownership and public-risk signals for Example Company.",
  "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 until the status is completed, failed, or cancelled. While active, a run can be queued, starting, or running. If the budget limit stops research, failure_code is CREDIT_BUDGET_EXCEEDED. The response also includes timestamps and a safe failure message.

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 run ends. Failed or cancelled runs may still have a report. Check partial, gaps, and warnings before using it. A report does not mean the research succeeded. REPORT_NOT_READY means you should wait for Retry-After. REPORT_UNAVAILABLE means there is no stored report to read. Reading a report does not start new research.

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.