REST API Reference
The hosted service at https://memory.neo4jlabs.com/v1 exposes a REST API.
This page is a curated companion to the machine-readable contract — it maps
every endpoint to its bridge-protocol equivalent and the corresponding method
on each language client.
|
The authoritative, always-current contract is the OpenAPI document at memory.neo4jlabs.com/openapi.json (production). Request/response schemas live there; this page covers the cross-cutting rules — auth, versioning, errors, pagination — and the SDK-method mapping the spec doesn’t show. |
Bridge-method names are what the agent-memory-tck cross-language conformance suite uses. SDK methods take language-idiomatic casing.
Base URL & versioning
All endpoints are served under a major-version prefix: the production base URL
is https://memory.neo4jlabs.com/v1. The SDK appends paths to the configured
MEMORY_ENDPOINT (default the URL above). The /v{n} prefix also selects the
REST transport; endpoints without it use the TCK bridge protocol (see
Bolt vs NAMS).
|
The active workspace is resolved from the API key (and/or the |
Request headers
Every request carries Authorization: Bearer <token>, where the token is either
your API key (nams_…) used directly, or a short-lived JWT obtained from the
Auth0 exchange endpoints (POST /v1/auth/exchange, POST /v1/auth/refresh).
The target workspace depends on the key’s category (see
Authentication & API Keys): a workspace
key is already bound to one workspace, so X-Workspace-Id is optional (and a
different value is rejected with 403); an admin key names the workspace
per request with X-Workspace-Id: <workspace_id>. The SDK sends the header
automatically when workspace_id / workspaceId (or MEMORY_WORKSPACE_ID) is
configured. See Use NAMS.
Conversations
| HTTP | Path | Bridge | TS | Go | Py | C# |
|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Because extraction runs asynchronously on NAMS, get_extraction_status (short-term
memory) is the authoritative "has the pipeline finished?" signal for a
conversation — long_term.wait_for_extraction(session_id=…) polls it for you.
Entities
| HTTP | Path | Bridge | TS | Go | Py | C# |
|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
POST /graph/expand returns the 1-hop neighbourhood of a node ({nodes, edges}),
excluding any loaded_ids you already have — it backs incremental
graph-visualization ("expand this node"). Exposed as long_term.expand_graph /
longTerm.expandGraph.
Reasoning
| HTTP | Path | Bridge | TS | Go | Py | C# |
|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Cypher and Auth
| HTTP | Path | Bridge | TS | Go | Py | C# |
|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The per-language method names above follow the bridge-protocol/conformance
naming. Both SDKs expose these on a |
Ontologies
Typed, versioned domain schemas. Workspace-scoped via X-Workspace-Id. Request
bodies are snake_case. See Ontology API for the
document schema and validation modes.
| HTTP | Path | Python | TypeScript |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Errors
Error responses use standard HTTP status codes with a JSON body of the shape
{"error": "<message>"}. Some errors carry extra fields (e.g. message,
limit on quota errors). The SDK maps them to typed exceptions:
| Status | Meaning | Python SDK exception |
|---|---|---|
|
Invalid request, write Cypher attempted, validation failure |
|
|
Missing/invalid token, or workspace not accessible |
|
|
Resource not found |
|
|
Operation not available on this backend |
|
|
Rate limited |
|
|
Service error |
|
Other 4xx (e.g. |
Conflict, gone, payload too large, semantic validation |
|
All SDK exceptions subclass MemoryError. The SDK retries 429, 5xx, and
network errors with exponential backoff, honoring any Retry-After header. See NAMS Limits & Behavior
for rate-limit and quota specifics.
Pagination
List endpoints accept limit and offset query parameters for offset-based
pagination (e.g. GET /v1/conversations?limit=50&offset=100). Defaults are
service-configured; pass an explicit limit for deterministic page sizes.
Wire format differences
-
Hosted REST: camelCase fields (
userId,conversationId,createdAt). -
Bridge protocol: snake_case fields (
user_id,conversation_id,created_at).
The clients translate transparently. If you’re writing a custom transport,
see the bridge-protocol reference
and the language-specific casing modules in the TCK repo.