Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.reasonblocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Everything you need to make your first authenticated request.

​
Base URL

EnvironmentBase URL
Production (hosted)https://rb-api.reasonblocks.com
Self-hostedhttp://<your-host>:8000 (see self-hosting)
All public routes are versioned under /v1/. Example: 
POST https://rb-api.reasonblocks.com/v1/traces/retrieve
Unversioned aliases like POST /traces/retrieve still work for SDK clients pinned to older paths, but are hidden from the public OpenAPI schema. Target /v1/... for new integrations. See versioning for the back-compat policy.

​
Get an API key

Three credential paths are accepted, in order of who should use each:
1

Per-customer API keys (external integrators)

Issue these from the dashboard. Each key is scoped to an org_id and optionally a project_id. The server uses the key’s scope as the authoritative tenant identity — body fields like org_id are ignored, so a customer can’t write into another tenant by tampering with payload values.Production keys start with rb_live_; test keys start with rb_test_.
2

Static keys (self-hosted, CI, dev)

Set REASONBLOCKS_KEYS=key1,key2 as a comma-separated env var on the server. Static keys have no org scope; routes that need a tenant accept org_id in the request body.
3

Supabase JWT (dashboard only)

Used by the ReasonBlocks dashboard UI on behalf of a signed-in user. External integrators should not use this path.

​
Authenticate

Every request must carry the bearer token: 
curl https://rb-api.reasonblocks.com/v1/traces/retrieve \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context":"refactor auth middleware","tier":"e1","top_k":3}'
A missing or invalid key returns 401. A revoked key returns 401 within about 60 seconds (server-side auth cache TTL).

​
First request

Sanity-check the service: 
curl https://rb-api.reasonblocks.com/health
# -> {"status":"ok","version":"0.1.0"}
Then try a real call: 
curl https://rb-api.reasonblocks.com/v1/traces/retrieve \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context":"fix flaky test in payment service","tier":"e1","top_k":3}'
A successful response is 200 with {"traces": [...]}. An empty array is valid — it means no patterns matched, or you’re over the monthly intervention cap.

​
Self-hosting

The service runs as a single FastAPI process. Minimum environment variables:
VariableRequired forNotes
REASONBLOCKS_KEYSStatic key authComma-separated. Empty disables static auth.
QDRANT_URL/v1/traces/retrieve returning real patternsOtherwise retrieval returns [].
QDRANT_API_KEYSame as above
OPENAI_API_KEYE1 / E2 similarity queriesE3 (scroll-all) works without it.
SUPABASE_URLPer-customer keys and JWT authBoth auth paths read from Supabase.
SUPABASE_SERVICE_KEYSame as above
SUPABASE_JWT_SECRETDashboard JWT auth
SUPABASE_DB_URL/v1/monitor/stream SSE live updatesFalls back to 503 when unset.
CORS_ALLOWED_ORIGINSBrowser-side dashboardsComma-separated origins.
Docker: 
docker build -t rb-api .
docker run -p 8000:8000 --env-file .env rb-api
The Dockerfile and migrations/ directory live at the rb-api repo root.

​
Rate limits

Per-principal sliding-window limiter (1-second token bucket). Each API key gets its own bucket.
SettingDefaultEnvironment variable
Sustained rate per key200 / secondRATE_LIMIT_PER_SEC
Burst400RATE_LIMIT_BURST
Body size cap5 MBMAX_BODY_BYTES
Exceeding the rate returns 429 with Retry-After: 1.
Per-key custom quotas (override the global default for specific customers) are tracked separately. Reach out if you need a different limit on your key.

​
CORS

The CORS allowlist is explicit — no wildcards combined with credentials. Set CORS_ALLOWED_ORIGINS to a comma-separated list of origins. Localhost dev origins are added only when CORS_ALLOW_DEV_ORIGINS=true.

​
Error codes

Standard HTTP status codes. Bodies are JSON of shape {"detail": "<reason>"} on 4xx and 5xx.
StatusMeaning
400Validation failure or malformed request
401Missing or invalid Authorization bearer
403Authenticated, but lacking access to the requested org or resource
404Resource not found — or a tenant mismatch hidden as 404 so resource IDs can’t be enumerated
413Request body exceeded MAX_BODY_BYTES
422Pydantic schema violation (field-level)
429Rate limited
5xxServer-side error; safe to retry with backoff

​
Next steps

Custom harness quickstart

Three HTTP calls to wire ReasonBlocks into your own agent loop.

Interactive OpenAPI

Browse every endpoint and try requests inline.