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.
Auto-merged entity creates
When POST /entities resolves a name to an existing entity, it returns a
resolution: "merged" envelope instead of a complete entity. Python
add_entity and TypeScript addEntity fetch the canonical entity and return it.
Both expose the create operation’s resolution in entity.metadata under the
reserved nams_resolution key, preserving other entity metadata:
{
"nams_resolution": {
"resolution": "merged",
"merged_into": "00000000-0000-0000-0000-000000000001",
"merge_confidence": 0.93,
"fallback": false
}
}merge_confidence is the service’s name-match score and is omitted when absent
or null. It does not replace the canonical entity’s own confidence.
If the canonical GET returns 404, an empty body, or an incomplete response
without a usable name, the SDK can return a fallback using the server-provided
merge ID and requested name/type. fallback: true identifies this result;
its creation timestamp is generated by the client, not read from the server.
Python uses its entity confidence default of 1.0; TypeScript leaves entity
confidence undefined. These fallback values are not estimates of stored
canonical values. Missing merge IDs and malformed populated fields are
validation errors. Authentication, rate-limit, network, and server errors
propagate to the caller instead of returning a fallback.
Ordinary creates and review_pending responses return their entity directly
without a follow-up GET.
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.
The TypeScript REST transport reports 404 as TransportError with
statusCode === 404; its exported NotFoundError is not used by that transport.
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.