API Reference

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.

Authentication

The X-Orakle-API-Key header and 401 behavior.

Jobs

Submit a pricing job and read its status and result.

Streaming

Open the SSE stream, replay with Last-Event-Id, keepalive.

Events

Every customer event type and its payload shape.

Errors

Error codes, HTTP statuses, and rate limiting.

Quick reference

One-screen table of every public endpoint.

End to end

# 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"

Prefer an SDK

The TypeScript SDK 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.