API

Three on-ramps. Same dossier.

Whichever surface you use — authenticated REST, native MCP tools, or x402 pay-per-call — the response shape is identical. Pick the on-ramp that matches who's calling.

REST

Submit a job over HTTPS.

Use a session cookie (after sign-in) or an API key (Growth+).

POST/api/jobs

Create a judgment job

Returns a job_id immediately. The actual run completes async (≤2 min); poll /api/jobs/{id} or wait on the webhook.

request

{
  "name": "Q2 board prep",
  "kind": "triage",
  "judgments": ["triage", "flight-risk", "warm-intro"],
  "profile_urls": [
    "https://linkedin.com/in/maya-rao",
    "https://linkedin.com/in/jordan-kim"
  ],
  "webhook_url": "https://hooks.acme.dev/people-intel"
}

response

{
  "ok": true,
  "job_id": "8a3f...",
  "profile_count": 2,
  "credits_reserved": 3.0,
  "atomic_reserved": 3000,
  "status": "running"
}

GET/api/jobs/[id]

Status + signed dossier URL

When succeeded, includes a 10-minute signed S3 URL pointing at the dossier JSON.

response

{
  "ok": true,
  "job": {
    "id": "8a3f...",
    "name": "Q2 board prep",
    "status": "succeeded",
    "profile_count": 2,
    "results_count": 2,
    "credits_spent": "3000"
  },
  "preview_url": "https://s3.../dossier.json?X-Amz-..."
}

GET/api/jobs

List recent jobs

50 most recent jobs for the authenticated household.

MCP

Native tools for AI assistants.

Connect Claude, ChatGPT, the Ounie AI Team, or any MCP-compatible client to https://people-intel.ounie.com/api/mcp. Auth with Authorization: Bearer pik_live_… — or append ?api_key=pik_live_…to the URL if your client can't set headers (e.g. the Ounie AI Team's manual MCP entry). Calls draw the key owner's Ounie credits; when the balance runs short a run is refused with a top-up link — an agent can never overdraw.

submit_judgment

Start a judgment job

get_job_status

Poll status, get signed URL

list_jobs

Recent jobs for the household

export_csv

Signed CSV download

get_credit_balance

Current credit balance

list_plans

Public: tiers, packs, judgments

whoami

API-key metadata

# Claude / claude-code MCP config
{
  "mcpServers": {
    "people-intel": {
      "url": "https://people-intel.ounie.com/api/mcp",
      "headers": { "Authorization": "Bearer pik_live_..." }
    }
  }
}

x402

Pay per read. No account.

currently unavailable

The pay-per-call rail is temporarily closed. POST /api/x402/read returns 503 with a Retry-After header and no payment quote — no 402, no accepts array, nothing to sign against. We would rather refuse than quote a price we cannot honour, because settlement on this rail is final and cannot be refunded. The credits rail below is unaffected. The shape documented here is what returns when the rail reopens.

Settle in USDC on Base. First call returns HTTP 402 + the payment requirements; second call (with the settled X-Payment header) returns the dossier.

POST/api/x402/read

Single profile read

$0.25 for one judgment, $0.40 for all five.

request

{
  "profile_url": "https://linkedin.com/in/maya-rao",
  "judgments": ["triage", "flight-risk"]
}

response

{
  "ok": true,
  "payment": { "tx_hash": "0x..", "paid_atomic_usdc": "400000" },
  "dossier": {
    "profile": { /* 22+ fields */ },
    "judgments": [ { "kind": "triage", "score": 91, ... }, ... ]
  }
}

Webhooks

Push instead of poll.

Pass webhook_url on job creation. We POST a single notification on completion.

POST https://your-app.com/people-intel-webhook
{ "job_id": "8a3f...", "status": "succeeded", "results_count": 248 }

Availability

We refuse before we charge.

A scheduled probe checks that our profile engine can actually start work. While it cannot, every billable endpoint answers 503 with a Retry-After header instead of quoting a price — no credits are reserved, no ledger entry is written, and no payment is requested or settled. Agents on the x402 rail get no 402 and no accepts array, so there is nothing to sign against. Service resumes on its own within minutes of the engine recovering.

HTTP/1.1 503 Service Unavailable
Retry-After: 300

{ "error": "upstream_unavailable",
  "detail": "People Intel is temporarily unavailable. Nothing was charged. Please try again shortly.",
  "charged": false,
  "retry_after_seconds": 300 }