Reason HTTP API

reason.oka.so exposes the full Reason intelligence layer over HTTP. If you’re using an MCP-compatible client, prefer the MCP interface — it wraps these endpoints with fire-and-forget buffering and automatic retry.

Base URL

Environment	URL
Production	https://reason.oka.so
Dev	https://reason.dev.oka.so

Authentication

All endpoints except /health require a JWT token:

curl https://reason.oka.so/api/learnings/context/auth \
  -H "Authorization: Bearer $OKA_API_KEY"

The token must include sub (user ID) and optionally account_id / org_id for multi-tenant scoping. All queries are automatically scoped to your account.

Key endpoints

Context (the flagship query)

# Get everything the organization knows about auth
curl "https://reason.oka.so/api/learnings/context/auth?limit=5&min_confidence=0.5" \
  -H "Authorization: Bearer $OKA_API_KEY"

Returns ranked learnings with confidence scores, evidence counts, and matching strategy metadata. Uses hybrid search (semantic + lexical) with automatic fallback.

Ingest events

curl -X POST https://reason.oka.so/api/reasoning/ingest \
  -H "Authorization: Bearer $OKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_type": "decision",
      "payload": {
        "decision": "Using pgvector for semantic search",
        "rationale": "Keeps the stack simple",
        "alternatives": "Pinecone, Qdrant"
      }
    }]
  }'

Browse learnings

# High-confidence architecture learnings
curl "https://reason.oka.so/api/reasoning/learnings?category=architecture&min_confidence=0.7&sort_by=confidence" \
  -H "Authorization: Bearer $OKA_API_KEY"

Semantic search

curl "https://reason.oka.so/api/reasoning/search?q=webhook+delivery+failures&limit=5" \
  -H "Authorization: Bearer $OKA_API_KEY"

Trigger consolidation

# Synchronous (blocks up to 120s)
curl -X POST https://reason.oka.so/api/reasoning/consolidate \
  -H "Authorization: Bearer $OKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_events": 200}'

# Asynchronous (returns immediately with poll URL)
curl -X POST https://reason.oka.so/api/reasoning/consolidate/async \
  -H "Authorization: Bearer $OKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Submit feedback

curl -X POST https://reason.oka.so/api/reasoning/feedback \
  -H "Authorization: Bearer $OKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "learning_id": "uuid-here",
    "useful": true,
    "reason": "This was exactly the context I needed"
  }'

Error responses

Status	Meaning
202	Accepted (async ingest/consolidation)
400	Invalid request body or parameters
401	Missing or invalid JWT
402	Plan limit exceeded for this meter (see Usage, plans & limits)
404	Resource not found (or wrong account)
408	Consolidation timed out (120s limit)
429	Rate limit exceeded — check Retry-After header
503	Embedding provider not configured (semantic search)

All errors return {"statusCode": N, "message": "..."}.

Rate limits

Default: 600 requests/minute per account. The 429 response includes Retry-After and X-RateLimit-Reset headers.

Full reference