API

REST Endpoints

Curl-first examples for Orbit endpoints. Protected routes require Bearer JWT or Orbit API key.

Credential source

Orbit Cloud users should create keys in Dashboard and replace <jwt-token> with orbit_pk_.... Self-hosted users can keep JWT.

Need full non-SDK app examples? See Direct API (No SDK) for Node.js, Python, and Go samples.

POST /v1/ingest

ingest.sh
curl -X POST http://localhost:8000/v1/ingest \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Idempotency-Key: ingest-alice-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I keep confusing while loops and for loops",
    "event_type": "user_question",
    "entity_id": "alice"
  }'

GET /v1/retrieve

retrieve.sh
curl "http://localhost:8000/v1/retrieve?query=What%20should%20I%20know%20about%20alice?&entity_id=alice&limit=5" \
  -H "Authorization: Bearer <jwt-token>"

POST /v1/feedback

feedback.sh
curl -X POST http://localhost:8000/v1/feedback \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Idempotency-Key: feedback-alice-0001" \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "<memory-id>", "helpful": true, "outcome_value": 1.0}'

POST /v1/ingest/batch

ingest-batch.sh
curl -X POST http://localhost:8000/v1/ingest/batch \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Idempotency-Key: ingest-batch-001" \
  -H "Content-Type: application/json" \
  -d '{"events": [
    {"content": "Lesson 1 complete", "event_type": "learning_progress", "entity_id": "alice"},
    {"content": "Lesson 2 complete", "event_type": "learning_progress", "entity_id": "alice"}
  ]}'

GET /v1/health

health.sh
curl http://localhost:8000/v1/health

GET /v1/status

Returns account usage, storage footprint, and quota counters.

status.sh
curl http://localhost:8000/v1/status \
  -H "Authorization: Bearer <jwt-token>"

POST /v1/dashboard/keys

dashboard-issue.sh
curl -X POST http://localhost:8000/v1/dashboard/keys \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"frontend-prod","scopes":["read","write","feedback"]}'

GET /v1/dashboard/keys

dashboard-list.sh
curl "http://localhost:8000/v1/dashboard/keys?limit=10" \
  -H "Authorization: Bearer <jwt-token>"

POST /v1/dashboard/keys/{key_id}/rotate

dashboard-rotate.sh
curl -X POST http://localhost:8000/v1/dashboard/keys/<key-id>/rotate \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"frontend-prod-rotated","scopes":["read","write","feedback"]}'

POST /v1/dashboard/keys/{key_id}/revoke

dashboard-revoke.sh
curl -X POST http://localhost:8000/v1/dashboard/keys/<key-id>/revoke \
  -H "Authorization: Bearer <jwt-token>"

GET /v1/metrics

Prometheus scrape endpoint for runtime and API metrics.

metrics.sh
curl http://localhost:8000/v1/metrics

Next

FastAPI Integration ->