API

API Reference

Orbit exposes the same core loop in SDK and REST form: ingest, retrieve, feedback, status.

Authentication

All protected endpoints require Authorization: Bearer <token> (JWT or Orbit API key).

For Orbit Cloud, create/manage API keys in Dashboard. API key material is shown once at creation/rotation.

Required JWT claims: sub, iat, exp, iss, aud. POST endpoints support idempotency via Idempotency-Key. Dashboard key endpoints require write scope (or keys:write).

SDK methods

Sync client: MemoryEngine. Async client: AsyncMemoryEngine with async equivalents.

Method

Returns

Description

ingest(content, event_type?, metadata?, entity_id?)

IngestResponse

Write one memory event

retrieve(query, limit?, entity_id?, event_type?, time_range?)

RetrieveResponse

Fetch ranked memory context

feedback(memory_id, helpful, outcome_value?)

FeedbackResponse

Send outcome signal for learning

status()

StatusResponse

Usage, storage, quota status

ingest_batch(events)

list[IngestResponse]

Batch ingest for throughput

feedback_batch(feedback)

list[FeedbackResponse]

Batch feedback writes

REST endpoints

Method

Path

Description

POST

/v1/ingest

Store one memory event

GET

/v1/retrieve

Retrieve ranked memories

POST

/v1/feedback

Store feedback signal

POST

/v1/ingest/batch

Batch event ingest

POST

/v1/feedback/batch

Batch feedback ingest

GET

/v1/status

Quota and storage visibility

GET

/v1/health

Health/liveness check

GET

/v1/metrics

Prometheus metrics

GET

/v1/memories

List stored memories

POST

/v1/auth/validate

JWT validation endpoint

POST

/v1/dashboard/keys

Issue API key (returns plaintext once)

GET

/v1/dashboard/keys

List keys (paginated)

POST

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

Revoke one key

POST

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

Rotate key (create new + revoke old)

Rate limit and idempotency headers

>X-RateLimit-Limit

>X-RateLimit-Remaining

>X-RateLimit-Reset

>Retry-After (on 429)

>X-Idempotency-Replayed (true|false)

Inference metadata in retrieval responses

For inferred facts and conflict guards, Orbit includes both provenance and normalized fact metadata in memory.metadata.

metadata = {
  "intent": "inferred_user_fact_conflict",
  "inference_provenance": {
    "inference_type": "fact_conflict_guard_v1",
    "clarification_required": true,
    "conflicts_with_memory_ids": ["<memory-id>"]
  },
  "fact_inference": {
    "fact_key": "allergy:pineapple",
    "fact_type": "constraint",
    "status": "contested",
    "clarification_required": true
  }
}

SDK Methods ->