# API Reference (/docs/api)

The Orakle HTTP API — submit a pricing job, stream progress over SSE, read the calibrated result.



Base URL: `https://api.orakle.xyz`. Authenticate every request with the
`X-Orakle-API-Key` header. All responses are JSON unless you open a stream.

Pricing is asynchronous. You `POST` a job and immediately get back a `job_id`
plus a `poll_url` and `stream_url`. The job moves through
`pending → processing → completed | failed`; you either stream Server-Sent
Events for live progress and the final result, or poll the status endpoint
until it is terminal.

<Cards>
  <Card title="Authentication" href="/docs/api/authentication" description="The X-Orakle-API-Key header and 401 behavior." />

  <Card title="Jobs" href="/docs/api/jobs" description="Submit a pricing job and read its status and result." />

  <Card title="Streaming" href="/docs/api/streaming" description="Open the SSE stream, replay with Last-Event-Id, keepalive." />

  <Card title="Events" href="/docs/api/events" description="Every customer event type and its payload shape." />

  <Card title="Errors" href="/docs/api/errors" description="Error codes, HTTP statuses, and rate limiting." />

  <Card title="Quick reference" href="/docs/api/reference" description="One-screen table of every public endpoint." />
</Cards>

## End to end [#end-to-end]

```bash
# 1. Submit a job → 202 with job_id, poll_url, stream_url
curl -s https://api.orakle.xyz/v1/jobs \
  -H "X-Orakle-API-Key: $ORAKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_type":"nl","query":"iPhone 15 Pro 128GB Grade B unlocked","geography":"US"}'

# 2. Stream progress and the final result (job_id from step 1)
curl -N https://api.orakle.xyz/v1/jobs/<job_id>/stream \
  -H "X-Orakle-API-Key: $ORAKLE_API_KEY"

# 3. Or poll until status is completed | failed
curl -s https://api.orakle.xyz/v1/jobs/<job_id> \
  -H "X-Orakle-API-Key: $ORAKLE_API_KEY"
```

<Callout title="Prefer an SDK">
  The [TypeScript SDK](/docs/sdks/typescript) wraps submit → stream → result
  into one call. Use the raw API for other stacks or full wire-level control.
  Working inside an AI client? See the [MCP server](/docs/mcp).
</Callout>