Documentation

Auth service base URL: https://memory.neo4jlabs.com Returns the public RSA key(s) used to verify NAMS JWTs. Used by other services for token validation.

Auth service base URL: https://memory.neo4jlabs.com List API keys owned by the authenticated user. Raw key values are never returned - only metadata (ID, label, created/revoked/expiry timestamps).

{
  "keys": [
    "..."
  ]
}

{
  "error": "No user in token"
}

{
  "error": "Internal error"
}

Auth service base URL: https://memory.neo4jlabs.com Generate a new API key owned by the authenticated user. The raw key is returned to the caller immediately and additionally stored encrypted-at-rest so it can be revealed again from the dashboard. It is bcrypt-validated on every request. Scopes default to all if omitted.

{
  "label": "string",
  "scopes": [
    "string"
  ]
}

{
  "id": "string",
  "key": "string",
  "label": "string"
}

{
  "error": "Missing required fields"
}

{
  "error": "No user in token"
}

{
  "error": "Internal error"
}

Auth service base URL: https://memory.neo4jlabs.com Revoke an API key by ID. The key is immediately invalidated - any active JWTs issued from it are blocklisted. This action is irreversible. Owner-only: only the user who owns the key can revoke it. Non-owners receive 404 (indistinguishable from a missing key) to prevent key-id enumeration.

{
  "status": "success"
}

{
  "error": "No user in token"
}

{
  "error": "Key not found or not owned by caller"
}

{
  "error": "Internal error"
}

Auth service base URL: https://memory.neo4jlabs.com Returns the decrypted raw API key value for keys created with encrypted storage. Owner-only: only the user who owns the key can reveal it. Non-owners receive 404 (indistinguishable from a missing key) to prevent credential disclosure and key-id enumeration. Returns 410 if the key was revoked or predates encrypted storage.

{
  "id": "string",
  "key": "string"
}

{
  "error": "No user in token"
}

{
  "error": "Key not found or not owned by caller"
}

{
  "error": "Key revoked or not revealable"
}

{
  "error": "Internal error"
}

Auth service base URL: https://memory.neo4jlabs.com Mint a new API key inheriting the old key's label and scopes, and atomically revoke the old one. The new raw key is returned exactly once in the response (and is also persisted encrypted-at-rest so it can be revealed again later). Owner-only: only the user who owns the key can rotate it. Non-owners receive 404 (indistinguishable from a missing key) to prevent key-id enumeration.

{
  "id": "string",
  "key": "string",
  "label": "string"
}

{
  "error": "No user in token"
}

{
  "error": "Key not found or not owned by caller"
}

{
  "error": "Key is already revoked"
}

{
  "error": "Internal error"
}

Auth service base URL: https://memory.neo4jlabs.com Validate an Auth0 Bearer token via JWKS and return per-workspace NAMS JWTs. Automatically provisions a default workspace for first-time users. Returns an array of {workspace_id, token} pairs - one per workspace the user belongs to.

{
  "workspaces": [
    "..."
  ]
}

{
  "error": "Invalid or missing token"
}

{
  "error": "Internal error"
}

{
  "error": "Auth0 exchange not configured"
}

Auth service base URL: https://memory.neo4jlabs.com Handles OAuth2 authorization code flow. Exchanges the provider code for user info and returns a NAMS JWT. Currently returns 501 - implementation pending.

{
  "code": "string",
  "provider": "string"
}

{
  "error": "Not implemented"
}

Auth service base URL: https://memory.neo4jlabs.com Exchange a refresh token for a new access token and rotated refresh token.

{
  "client_id": "string",
  "refresh_token": "string"
}

{
  "refresh_token": "string",
  "token": "string"
}

{
  "error": "Invalid request"
}

{
  "error": "Invalid or expired refresh token"
}

{
  "error": "Internal error"
}

List all conversations for the workspace. Returns metadata only (no messages).

{
  "conversations": [
    "..."
  ]
}

{
  "error": "Internal error"
}

Create a new conversation session. Returns the conversation ID used for all subsequent message, context, and search calls. Entity extraction runs asynchronously after messages are added.

{
  "metadata": {},
  "userId": "string"
}

{
  "id": "string",
  "metadata": {},
  "userId": "string",
  "workspaceId": "string"
}

{
  "error": "workspace_id required"
}

{
  "error": "Internal error"
}

Delete a conversation and all its messages.

{
  "status": "success"
}

{
  "error": "Internal error"
}

Get conversation metadata by ID.

{
  "createdAt": "string",
  "id": "string",
  "metadata": {},
  "updatedAt": "string",
  "userId": "string",
  "workspaceId": "string"
}

{
  "error": "Not found"
}

{
  "error": "Internal error"
}

Get the structured context for an agent to build its prompt from. Returns three tiers: (1) reflections - highest-level compressed insights, (2) observations - mid-level summaries, (3) recentMessages - raw recent messages. Call this before constructing an agent's system prompt.

{
  "observations": [
    "..."
  ],
  "recentMessages": [
    "..."
  ],
  "reflections": [
    "..."
  ]
}

{
  "error": "Internal error"
}

List messages in a conversation, newest first. Use the limit parameter to control page size (default 50, max 200).

{
  "messages": [
    "..."
  ]
}

{
  "error": "Internal error"
}

Add a message to a conversation. Triggers asynchronous entity extraction via the memory worker. Role must be "user", "assistant", or "system".

{
  "content": "string",
  "role": "string"
}

{
  "content": "string",
  "conversationId": "string",
  "id": "string",
  "role": "string"
}

{
  "error": "Invalid role or missing fields"
}

{
  "error": "Conversation not found"
}

{
  "error": "Internal error"
}

Add multiple messages to a conversation in a single request. Each message triggers async entity extraction independently. Maximum 100 messages per request.

{
  "messages": [
    "..."
  ]
}

{
  "messages": [
    "..."
  ]
}

{
  "error": "Validation error"
}

{
  "error": "Internal error"
}

Search messages within a conversation by content. Uses vector similarity search when embeddings are available, falling back to text CONTAINS. Returns searchType field indicating which method was used.

{
  "limit": 0,
  "query": "string"
}

{
  "messages": [
    "..."
  ],
  "searchType": "vector"
}

{
  "error": "Missing query"
}

{
  "error": "Internal error"
}

List all entities in the knowledge graph. Filter by type using the optional query parameter.

{
  "entities": [
    "..."
  ]
}

{
  "error": "Internal error"
}

Create a new entity in the knowledge graph. Entities are automatically created during entity extraction, but can also be created manually.

{
  "description": "string",
  "name": "string",
  "properties": {},
  "type": "string"
}

{
  "description": "string",
  "id": "string",
  "name": "string",
  "type": "string"
}

{
  "error": "Missing required fields"
}

{
  "error": "Internal error"
}

Get the full entity graph with nodes and edges for visualization. Used by the Memory Browser in the dashboard.

{
  "edges": [
    {}
  ],
  "nodes": [
    {}
  ]
}

{
  "error": "Internal error"
}

Search entities by name or description. Uses vector similarity search when embeddings are available, falling back to text CONTAINS. Returns searchType field indicating which method was used.

{
  "limit": 0,
  "query": "string",
  "type": "string"
}

{
  "entities": [
    "..."
  ],
  "searchType": "vector"
}

{
  "error": "Missing query"
}

{
  "error": "Internal error"
}

Delete an entity and all its relationships from the knowledge graph.

{
  "status": "success"
}

{
  "error": "Internal error"
}

Get entity details including all relationships (incoming and outgoing edges in the knowledge graph).

{
  "confidence": 0,
  "createdAt": "string",
  "description": "string",
  "id": "string",
  "name": "string",
  "relationships": [
    "..."
  ],
  "sourceStage": "string",
  "type": "string",
  "updatedAt": "string"
}

{
  "error": "Not found"
}

{
  "error": "Internal error"
}

Update an entity's name or description.

{
  "description": "string",
  "name": "string"
}

{
  "status": "success"
}

{
  "error": "Invalid request"
}

{
  "error": "Internal error"
}

Provide feedback on entity quality. userScore is a float 0-1 representing confidence. confirmed=true marks the entity as human-verified.

{
  "confirmed": false,
  "userScore": 0
}

{
  "id": "string",
  "updated": false
}

{
  "error": "Invalid request"
}

{
  "error": "Internal error"
}

Get cross-conversation history - all messages that mention this entity, across all conversations in the workspace.

{
  "entityId": "string",
  "mentions": [
    {}
  ]
}

{
  "error": "Internal error"
}

Merge the source entity into a target entity. All relationships are transferred to the target. A SAME_AS relationship is created for provenance. The source entity is not deleted but becomes inert.

{
  "targetId": "string"
}

{
  "sourceId": "string",
  "status": "merged",
  "targetId": "string"
}

{
  "error": "Missing targetId or attempted self-merge"
}

{
  "error": "Internal error"
}

List compressed observations for a conversation. Observations are auto-generated summaries of message windows, created by the memory worker after sufficient messages accumulate.

{
  "observations": [
    "..."
  ]
}

{
  "error": "Internal error"
}

List reflections for a conversation. Reflections are higher-level insights synthesized from multiple observations. Each new reflection supersedes the previous.

{
  "reflections": [
    "..."
  ]
}

{
  "error": "Internal error"
}

Get a detailed explanation of a reasoning step including its tool calls and the entities it influenced.

{
  "actionTaken": "string",
  "conversationId": "string",
  "createdAt": "string",
  "id": "string",
  "influencedEntities": [
    "..."
  ],
  "reasoning": "string",
  "result": "string",
  "toolCalls": [
    "..."
  ]
}

{
  "error": "Step not found"
}

{
  "error": "Internal error"
}

Get the reasoning chain that influenced the creation of an entity - which steps and tool calls contributed to it.

{
  "entityId": "string",
  "steps": [
    {}
  ]
}

{
  "error": "Internal error"
}

List reasoning steps for a conversation. The conversation_id query parameter is required.

{
  "steps": [
    "..."
  ]
}

{
  "error": "Missing conversation_id"
}

{
  "error": "Internal error"
}

Record a reasoning step taken by an agent. Captures the agent's thought process (reasoning), the action it decided to take (actionTaken), and optionally the result.

{
  "actionTaken": "string",
  "conversationId": "string",
  "reasoning": "string",
  "result": "string"
}

{
  "actionTaken": "string",
  "conversationId": "string",
  "id": "string",
  "reasoning": "string",
  "result": "string"
}

{
  "error": "Missing required fields"
}

{
  "error": "Internal error"
}

Record a tool invocation made by an agent during a reasoning step. Optionally link to a step via stepId. input and output must be JSON-encoded strings, not objects. Pre-serialize structured payloads before sending (e.g. "input": "{\"query\":\"foo\"}", not "input": {"query":"foo"}). The graph stores them as scalar string properties on the :ToolCall node. Status values: pending, success (default), failure, error, timeout, cancelled. Legacy completed/failed are accepted and rewritten to success/failure.

{
  "durationMs": 150,
  "input": "{\"query\":\"project status\"}",
  "output": "{\"results\":[\"r1\",\"r2\"]}",
  "status": "success",
  "stepId": "string",
  "toolName": "web_search"
}

{
  "id": "string",
  "status": "string",
  "stepId": "string",
  "toolName": "string"
}

{
  "error": "Missing required fields"
}

{
  "error": "Internal error"
}

Get the full reasoning trace for a conversation - all steps and their tool calls, in order.

{
  "conversationId": "string",
  "steps": [
    "..."
  ],
  "toolCalls": [
    "..."
  ]
}

{
  "error": "Internal error"
}

Runs caller-supplied Cypher against the tenant's graph database with Neo4j's READ access mode. Writes are rejected server-side. Returns columns, rows, and stats.

{
  "cypher": "string",
  "params": {}
}

{
  "columns": [
    "string"
  ],
  "rows": [
    {}
  ],
  "stats": {}
}

{
  "error": "Invalid query, write operation attempted, or Cypher error"
}

{
  "error": "Internal error"
}

{
  "error": "Query backend unavailable"
}

List all workspaces the authenticated user is a member of.

{
  "workspaces": [
    "..."
  ]
}

{
  "error": "no user identity"
}

Return details for the workspace identified by the X-Workspace-Id header.

{
  "createdAt": "string",
  "id": "string",
  "managedDbInactivityDays": 0,
  "name": "string",
  "plan": "string",
  "provisioningStage": "string",
  "status": "active",
  "statusMessage": "string"
}

{
  "error": "no workspace identity"
}

{
  "error": "workspace not found"
}

Return the workspace's database mode and connection info. The password is never included.

{
  "connection": {
    "database": "...",
    "expiresAt": "...",
    "password": "...",
    "uri": "...",
    "username": "..."
  },
  "connections": {
    "ro": "...",
    "rw": "..."
  },
  "mode": "managed",
  "sandboxActive": false
}

{
  "error": "Unauthorized"
}

{
  "error": "workspace not found"
}

Test reachability of an external Neo4j connection without storing anything. The URI is SSRF-validated.

{
  "database": "neo4j",
  "password": "secret",
  "uri": "neo4j+s://abc123.databases.neo4j.io",
  "username": "neo4j"
}

{
  "error": "connection failed",
  "success": false
}

{
  "error": "invalid uri",
  "success": false
}

Return all members of the workspace.

{
  "members": [
    "..."
  ]
}

{
  "error": "Unauthorized"
}

Return the workspace's typed-relation allowlist configuration, falling back to system defaults when unset.

{
  "allowed_types": [
    "string"
  ],
  "custom_descriptions": {},
  "enabled": true,
  "fallback_type": "RELATED_TO",
  "min_confidence": 0.5
}

{
  "error": "Unauthorized"
}

Return the workspace's entity-resolution configuration, falling back to system defaults when unset.

{
  "auto_merge_threshold": 0.92,
  "embedding_weight": 0.6,
  "enabled": true,
  "fuzzy_min_score": 0.5,
  "fuzzy_weight": 0.4,
  "review_threshold": 0.78,
  "semantic_min_score": 0.55,
  "top_k": 25,
  "type_strict": true
}

{
  "error": "Unauthorized"
}

Create a new workspace with status "pending". A database is not provisioned automatically — provisioning is a separate step that requires a user-token session (performed from the dashboard). Workspace names are unique per owner.

{
  "name": "my-workspace"
}

{
  "id": "string",
  "name": "string",
  "status": "pending"
}

{
  "error": "name is required"
}

{
  "error": "workspace_limit_reached"
}

{
  "error": "name_taken (includes existing_workspace_id)"
}