Use the tools you already use
OpenAPI 3 + GraphQL + SSE is what your engineers already know. We don't ship a proprietary SDK that locks you in.
Capability · API & GraphQL
REST, GraphQL, and Server-Sent Events. No proprietary SDK required.
Public REST surface with OpenAPI documentation, a single-round-trip GraphQL endpoint, and SSE streams for real-time updates. Scoped API keys, distributed bucket4j rate limiting, and idempotency keys on every mutation.
Overview
What it is, in one paragraph
Every public capability of RateStack is reachable over the public API. The REST surface follows RFC standards (idempotency keys, RFC 7807 errors, conditional headers), the GraphQL endpoint exposes a typed schema browser, and SSE endpoints stream pricing.computed and ratesheets.activated events. API keys are scoped, rate-limited per-key on a Redis-backed bucket4j, and protected with a SHA-256-hash store + brute-force lockout.
OpenAPI spec is live
The spec at /v3/api-docs is generated from the live api-service. It is the source of truth for SDK generation.
Idempotency keys
Every mutation accepts an Idempotency-Key (UUID v4). Replays return the original response. Prevents duplicate locks, duplicate webhooks, duplicate imports.
RFC 7807 problem details
Every error returns application/problem+json with type, title, detail, status, instance, and a stable correlationId field for log correlation.
Scoped API keys
Scopes: READ, WRITE, ADMIN. SHA-256 hash store; the plaintext key is shown once at creation. Brute-force lockout at the bucket level.
Distributed rate limit
bucket4j with Lettuce on Redis. One global counter per API key regardless of which api-service replica receives the request.
GraphQL with subscriptions
Single-round-trip pricing + drill-down via /graphql. Subscriptions deliver live pricing.computed events for SSE-friendly clients.
How it works
The pipeline, end to end.
Numbered steps from input to output. Each step maps to a specific subsystem you can inspect via OpenTelemetry.
- 1
Issue a key in the portal
/api-keys → Create. Pick a scope (READ / WRITE / ADMIN), a name, an optional expiration. The plaintext key is shown once.
- 2
Authenticate every request
Set X-API-Key on every REST and GraphQL request. SSE endpoints accept the header on the initial subscribe.
- 3
Read the OpenAPI spec
GET /v3/api-docs returns a live OpenAPI 3 document. Generate clients with openapi-generator, pin the schema in your CI, etc.
- 4
Use idempotency on writes
Generate a UUID v4 per logical operation; pass it as Idempotency-Key. Server caches the response keyed by (apiKey, idempotencyKey, body-hash) for 24 hours.
- 5
Handle problem+json
Errors come back with stable shape; correlationId in the body. Log it; if you need support, reference it.
- 6
Watch your burndown
GET /v1/api-keys/{id}/usage returns a per-minute sparkline + the live bucket4j snapshot. Alert on it before you exhaust.
Hands on
REST and GraphQL side by side
Live cURL sample — copy, paste, ship.
# REST + idempotency key + RFC 7807 errors
curl -X POST https://api.ratestack.com/v1/pricing/mode \
-H "X-API-Key: $RATESTACK_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "borrower": { "fico": 752 }, "pricingMode": "BEST_EX", ... }'
# GraphQL — pricing + drill-down in one call
curl -X POST https://api.ratestack.com/graphql \
-H "X-API-Key: $RATESTACK_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "query Price($input: LoanInput!) {
pricing(input: $input, mode: BEST_EX) {
quotes {
investorName productCode noteRate basePrice finalPrice
adjustments { description amount sign }
}
}
}",
"variables": { "input": { ... } }
}'Why this matters
The pain it removes.
Survive your own retries
Idempotency keys make retries safe by default. Network blip? Retry. Pod restart mid-write? Retry. Lock-day surge? Retry.
Predictable failure
RFC 7807 means your error handling is one switch on status, not a string-matching nightmare.
Frequently asked
Direct answers, no marketing spin.
Do you offer SDKs?
We publish first-party clients for JavaScript/TypeScript and Python. The OpenAPI spec is the source of truth — you can also generate clients in any language openapi-generator supports.
What's your rate limit?
Per-API-key buckets configured at issue time. Defaults: 60 req/s sustained, 200 req/s burst on Team; 600 req/s on Business; custom on Enterprise. The burndown endpoint shows the live bucket.
Do you support GraphQL subscriptions over WebSocket?
Subscriptions are delivered via SSE today. WebSocket is on the roadmap for environments that prefer it.
What's the auth story for browser apps?
Use the public-portal BFF pattern — your browser holds an opaque session cookie; the server-side proxy injects the API key. The plaintext key never reaches client JavaScript.
How we compare
REST, GraphQL, and Server-Sent Events. No proprietary SDK required. — vs the alternatives.
Specific angles, not generic feature checklists. Each row links to a longer side-by-side; we're transparent about where competitors are the better choice.
vs Optimal Blue
Open REST + GraphQL with a published OpenAPI spec — no priest-class certified-integrator gate.
See the side-by-sidevs Polly
Idempotency keys, RFC 7807 problem+json, scoped API keys — every behavior is documented at the wire level.
See the side-by-sidevs Lender Price
GraphQL drill-down in a single round-trip — pricing + per-rule trace in one query.
See the side-by-sidevs ICE Mortgage Pricing
No Encompass dependency. The API is self-contained and works with any LOS or none at all.
See the side-by-sideComparisons reflect each vendor's public positioning. Where a fact is unverifiable, we mark it "Depends" or "Unknown" instead of guessing.
Related capabilities
Pieces that work better together.
Ready to see it on your data?
Wire rest, graphql, and server-sent events. no proprietary sdk required. up to your real workflow.
We'll spin you a sandbox, load your actual ratesheets, and walk you through this capability against your top scenarios.