API Reference - Complete Endpoint Documentation

Curated core API resources and contracts. The deployed OpenAPI 3.1 document is canonical for the complete surface and code generation. Unless stated otherwise, endpoints require authentication in the Authorization header.

Base URL

https://api.hebbrix.com/v1

All API requests should be made to this base URL. HTTPS is required.

Contract status

GA: authentication, collections, raw and smart memory ingestion, search, chat, profile, graph CRUD/query, confidence, Outcome Memory, documents/media, billing, and privacy lifecycle endpoints documented here.
Beta: advanced reasoning, training, experimental agent, and specialized memory endpoints present in OpenAPI but not listed in this curated guide. Beta endpoints can evolve with changelog notice.
Internal/admin: routes tagged internal or admin are not a customer contract even when visible in the machine-readable schema; authorization remains deny-by-default.
Deprecated: OpenAPI's deprecated: true flag and the versioned changelog are authoritative.

Authentication

Include your API key in the Authorization header:

Authorization

Authorization: Bearer mem_sk_your_api_key

Learn more about authentication

Resources

Memories: Create, retrieve, update, and delete memory entries (/v1/memories)
Search: Adaptive semantic, lexical, graph, temporal, facet, and calibrated retrieval (/v1/search)
Chat Completions: OpenAI-compatible chat with memory injection (/v1/chat)
Collections: Organize memories into collections (/v1/collections)
Documents: Upload and process documents (/v1/documents)
Profile: User profile and preferences (/v1/profile)
Knowledge Graph: Entities and relationships (/v1/knowledge-graph)
Webhooks: Event notifications (/v1/webhooks)
Usage & Billing: Monitor usage and manage subscription (/v1/usage)
Outcome Memory & Feedback: Decision receipts, delayed outcomes, policy evidence, confidence, corrections, and feedback (/v1/learning)

All Endpoints

Memories

View documentation →

Field	Type	Description
POST /v1/memories	POST	Create a memory (Mem0-compatible)
POST /v1/memories/raw	POST	Direct memory creation (no ML)
POST /v1/memories/process	POST	Smart async extraction and conflict resolution (202 + job_id by default)
GET /v1/memories/jobs/{job_id}	GET	Poll a smart-ingestion job
POST /v1/memories/batch	POST	Batch create (max 100)
GET /v1/memories	GET	List all memories
GET /v1/memories/{id}	GET	Get a specific memory
PATCH /v1/memories/{id}	PATCH	Update a memory
DELETE /v1/memories/{id}	DELETE	Delete a memory
POST /v1/memories/bulk-delete	POST	Bulk delete by IDs (max 500)
DELETE /v1/memories/all	DELETE	Delete all memories

Search

View documentation →

Field	Type	Description
POST /v1/search	POST	Hybrid search across memories
POST /v1/search/advanced	POST	Advanced search with filters and boosting
GET /v1/search/similar/{id}	GET	Find similar memories
POST /v1/search/graph	POST	Knowledge graph search
POST /v1/search/reason	POST	Answer questions using memories + LLM

Chat Completions

View documentation →

Field	Type	Description
POST /v1/chat/completions	POST	Create chat completion

Collections

View documentation →

Field	Type	Description
POST /v1/collections	POST	Create a collection
GET /v1/collections	GET	List all collections
GET /v1/collections/default	GET	Get default collection
GET /v1/collections/{id}	GET	Get a collection
PATCH /v1/collections/{id}	PATCH	Update a collection
DELETE /v1/collections/{id}	DELETE	Delete a collection
POST /v1/collections/bulk-delete	POST	Bulk delete collections
DELETE /v1/collections/all	DELETE	Delete all collections

Documents

View documentation →

Field	Type	Description
POST /v1/documents/upload	POST	Upload a document (multipart form; `file` + optional `collection_id` as form fields)
GET /v1/documents	GET	List all documents
GET /v1/documents/{id}	GET	Get document details
GET /v1/documents/{id}/chunks	GET	Get document chunks
DELETE /v1/documents/{id}	DELETE	Delete a document

Profile

View documentation →

Field	Type	Description
GET /v1/profile	GET	Get user profile
PATCH /v1/profile	PATCH	Update profile
POST /v1/profile/dialectic	POST	Dialectic conversation
DELETE /v1/profile	DELETE	Delete profile

Knowledge Graph

View documentation →

Field	Type	Description
GET /v1/knowledge-graph/entities	GET	List entities
GET /v1/knowledge-graph/entities/{entity_name}	GET	Get entity details
POST /v1/knowledge-graph/entities	POST	Create an entity
DELETE /v1/knowledge-graph/entities/{entity_name}	DELETE	Delete an entity
POST /v1/knowledge-graph/relationships	POST	Create a relationship
DELETE /v1/knowledge-graph/relationships	DELETE	Delete a relationship
POST /v1/knowledge-graph/query	POST	Temporal query
GET /v1/knowledge-graph/timeline/{entity_name}	GET	Entity relationship timeline
GET /v1/knowledge-graph/contradictions	GET	Inspect contradiction evidence
GET /v1/knowledge-graph/stats	GET	Graph statistics

Webhooks

View documentation →

Field	Type	Description
POST /v1/webhooks	POST	Create a webhook
GET /v1/webhooks	GET	List webhooks
GET /v1/webhooks/{id}	GET	Get webhook details
PUT /v1/webhooks/{id}	PUT	Update a webhook
DELETE /v1/webhooks/{id}	DELETE	Delete a webhook
POST /v1/webhooks/{id}/test	POST	Send test event

Usage & Billing

View documentation →

Field	Type	Description
GET /v1/usage	GET	Get current usage
GET /v1/usage/history	GET	Usage history
GET /v1/billing/subscription	GET	Get subscription
POST /v1/billing/upgrade	POST	Upgrade plan
POST /v1/billing/downgrade	POST	Downgrade plan
GET /v1/billing/invoices	GET	List invoices

Outcome Memory & Feedback

View documentation →

Field	Type	Description
POST /v1/learning/decisions	POST	Choose or record an action receipt with candidates and propensity
GET /v1/learning/decisions/{id}	GET	Inspect a decision and its outcome evidence
POST /v1/learning/decisions/{id}/outcomes	POST	Report delayed, final, or corrected outcomes
GET /v1/learning/policies/{key}/insights	GET	Inspect posterior policy evidence and uncertainty
POST /v1/learning/policies/{key}/evaluate	POST	Conservatively evaluate whether evidence is sufficient
GET /v1/confidence	GET	Check act-vs-ask confidence for a query (?query=...)
POST /v1/corrections	POST	Store a correction (corrected_content + correction_type: preference\|factual\|procedural)
GET /v1/corrections/relevant	GET	Get corrections relevant to a task (?query=...)
POST /v1/decisions	POST	Log a decision + outcome (decision_type + description). Alias: POST /v1/decisions/log
GET /v1/decisions/similar	GET	Find similar past decisions (?query=...)
POST /v1/feedback/relevance	POST	Submit relevance feedback (memory_id, query, is_relevant)
POST /v1/feedback/ranking	POST	Submit ranking correction (memory_id, query, actual_rank, expected_rank)
POST /v1/feedback/missing	POST	Report a missing result (query, expected_content)
GET /v1/feedback/stats	GET	Aggregate feedback statistics

Response Format

All responses are JSON. Successful responses include the requested data:

200 OK

{
  "id": "mem_abc123",
  "content": "User prefers...",
  "created_at": "2024-01-15T..."
}

4xx/5xx Error

{
  "error": {
    "code": "invalid_request",
    "message": "...",
    "status": 400
  }
}

Learn more about error handling

Every response includes X-Request-ID, X-Process-Time, X-Hebbrix-Version, and X-Hebbrix-Build. Include the request ID and build ID in support reports. Retryable 429 and 503 responses include Retry-After.

Consistency, idempotency & terminal jobs

Memory writes, memory-tool inserts, corrections, and direct updates share one durable readiness contract. A ready create returns 201 and a ready update returns 200; work that is durably committed but still indexing returns 202 with searchable:false, Retry-After, Location, status_url, and outbox_event_id. Smart ingestion returns 202 + job_id by default and becomes searchable when its job reports completion.
Graph create responses return canonical entity or relationship IDs plus primary read-after-write and replica-delivery status. Use returned immutable IDs for later reads and deletes.
Collection deletion makes SQL-owned data unavailable atomically and durably queues external index, graph, cache, and object cleanup. A successful repeat returns the documented not-found/idempotent lifecycle result rather than recreating data.
Send Idempotency-Key on mutating requests. Reuse the same key and identical body when retrying; reusing a key with a different body is rejected.
Job states distinguish queued, processing, completed, and failed. A terminal media result additionally distinguishes a transcript from no_speech_detected.
Search returns calibrated score semantics plus no_match and abstain_recommended; never treat padded nearest neighbors as verified evidence.

Pagination

List endpoints use cursor-based pagination with limit and cursor parameters:

Cursor pagination

GET /v1/memories?limit=50&cursor=eyJpZCI6Im1lbV8xMjMifQ

Field	Type	Description
limit	default 50 / max 100	Number of items to return
cursor	default null	Cursor from previous response's next_cursor field

Response includes pagination metadata:

Pagination metadata

{
  "items": [...],
  "next_cursor": "eyJpZCI6Im1lbV83ODkifQ",
  "has_more": true,
  "total_count": 1250
}

Rate Limits

Rate limits vary by tier and endpoint. Check response headers for your current limits:

X-RateLimit-Limit: max requests
X-RateLimit-Remaining: remaining requests
X-RateLimit-Reset: reset timestamp
Retry-After: wait time (on 429)

View rate limits by tier

Get Started

Ready to start building? Check out our quickstart guide or explore the SDKs.