HTTP API

Base URL https://cracked-ai-pearl.vercel.app/v1. JSON in, JSON out. Auth: Authorization: Bearer ck_live_... (or an OAuth access token). Errors return { code, error, message }.

Method	Path	Auth	Purpose
POST	`/discover`	optional	Search tools. Body: `query`, `limit` (≤40), `minScore`, `liveOnly`, `includeUnavailable`, `category`, `provider`, `includeApify`.
POST	`/inspect`	optional	Schema, price, health. Body: `provider`, `endpoint`.
POST	`/run`	required	Execute. Body: `provider`, `endpoint`, `input`, `wait` (default true), `webhook_url`.
GET	`/runs`	required	Recent runs (`limit` ≤100).
GET	`/runs/:id`	required	One run with output. `?wait=30` long-polls an async run.
POST	`/runs/:id/stop`	required	Abort a running job.
GET	`/wallet/balance`	required	Balance, lifetime top-up, lifetime spend.
GET	`/wallet/activities`	required	Ledger rows with run ids.
GET	`/auth/whoami`	required	Workspace behind the token.
GET	`/auth/workspaces`	required	Workspaces the token or session can use.
GET	`/providers`	none	Full registry as JSON with live status and health.

Status codes

200 run finished (check status and providerResponse.httpStatus)
202 async run started or still running
400 bad input
401 missing, expired or invalid token
402 insufficient balance
404 unknown endpoint or run
429 key over its per-minute limit
503 provider not enabled (run recorded as BLOCKED, not billed)

Example

curl -s https://cracked-ai-pearl.vercel.app/v1/discover -H "content-type: application/json" -d '{"query":"sec filings mentioning glp-1"}'

curl -s https://cracked-ai-pearl.vercel.app/v1/run -H "Authorization: Bearer ck_live_..." -H "content-type: application/json" \
  -d '{"provider":"sec-edgar","endpoint":"/full-text-search","input":{"query":"GLP-1","forms":"10-K","limit":5}}'

Discover response

{ "query": "...", "count": 8, "results": [ {
    "provider": "sec-edgar", "providerName": "SEC EDGAR", "endpoint": "/full-text-search",
    "name": "Full-text filing search", "description": "...", "tags": ["sec","filings"],
    "category": "Finance & Crypto", "status": "live", "verified": true, "async": false, "score": 0.81,
    "price": { "type": "PER_CALL", "amount": 0.003 },
    "metrics": { "status": "healthy", "samples": 12, "successRate": 100, "medianMs": 640 },
    "hints": { "inspect": "POST /v1/inspect {...}", "run": "POST /v1/run {...}" } } ] }

Run response

{ "runId": "…", "provider": "web", "endpoint": "/fetch", "status": "COMPLETED",
  "output": { ... }, "providerResponse": { "httpStatus": 200, "error": null },
  "price": { "type": "PER_CALL", "amount": 0.003 },
  "billing": { "units": 1, "providerUsd": 0.003, "platformFeeUsd": 0.001, "totalUsd": 0.004, "byok": false, "balanceAfterUsd": 1.99 },
  "durationMs": 412, "createdAt": "…", "completedAt": "…" }

Rate limits

120 runs per minute per key by default. Discover and inspect are not rate limited. Async runs count once, at start.

Workspace header

Session-authenticated calls from the dashboard may pass x-workspace-id. API keys and OAuth tokens are bound to one workspace and ignore the header.