REST API Reference (Markdown)

<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/ur/api
  Generated: 2026-04-26T19:09:36.546Z
-->
# API and OpenAPI specification

The Neotoma REST API is defined in the [OpenAPI spec](https://github.com/markmhendrickson/neotoma/blob/main/openapi.yaml). The table below lists each endpoint and the capability it provides.

The API is designed around deterministic state operations: store structured observations, retrieve snapshots with provenance, and manage typed relationships explicitly.

## Base URL

-   **Development:** `http://localhost:3080`
-   **Production:** `http://localhost:3180` (local) or your deployed host

◆

## Authentication

All endpoints except `/health` and `/openapi.yaml` require a Bearer token:

Authorization: Bearer <NEOTOMA\_BEARER\_TOKEN>

-   Set via `NEOTOMA_BEARER_TOKEN` environment variable
-   When encryption is enabled, use the key-derived MCP token instead: `neotoma auth mcp-token`
-   MCP OAuth endpoints (`/mcp/oauth/*`) have their own auth flow - see the [MCP reference](/mcp)

◆

## Request examples

\# Store structured entities
curl -X POST http://localhost:3080/store \\
  -H "Authorization: Bearer $NEOTOMA\_BEARER\_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"entities":\[{"entity\_type":"task","title":"Review schema changes","status":"open"}\]}'

# Query entities
curl -X POST http://localhost:3080/entities/query \\
  -H "Authorization: Bearer $NEOTOMA\_BEARER\_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"filters":{"entity\_type":"task"},"limit":10}'

# Retrieve snapshot with provenance
curl -X POST http://localhost:3080/get\_entity\_snapshot \\
  -H "Authorization: Bearer $NEOTOMA\_BEARER\_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"entity\_id":"<entity\_id>"}'

# Upload a file
curl -X POST http://localhost:3080/upload\_file \\
  -H "Authorization: Bearer $NEOTOMA\_BEARER\_TOKEN" \\
  -F "file=@document.pdf"

# Health check (no auth required)
curl http://localhost:3080/health

| Method | Endpoint | Description | Parameters |
| --- | --- | --- | --- |
| GET | /me | Get the current user. | — |
| POST | /mcp/oauth/initiate | Initiate the OAuth flow. | body: auth\_provider, redirect\_uri |
| GET | /mcp/oauth/authorize | Handle the OAuth authorize redirect. | query: code, state |
| POST | /mcp/oauth/token | Exchange the OAuth code for a token. | body: code, code\_verifier |
| GET | /mcp/oauth/status | Get OAuth connection status. | — |
| GET | /mcp/oauth/connections | List OAuth connections. | — |
| DELETE | /mcp/oauth/connections/{id} | Remove an OAuth connection. | path: id |
| POST | /entities/query | Query entities with filters. | body: filters, limit, offset |
| GET | /entities/{id} | Get an entity by ID. | path: id |
| POST | /get\_entity\_snapshot | Get an entity snapshot with provenance. | body: entity\_id, at? |
| GET | /entities/{id}/observations | List observations for an entity. | path: id |
| POST | /list\_observations | List observations by query. | body: filters |
| POST | /get\_field\_provenance | Get provenance for a field. | body: entity\_id, field |
| GET | /entities/{id}/relationships | List relationships for an entity. | path: id |
| POST | /list\_relationships | List relationships by query. | body: filters |
| POST | /retrieve\_entity\_by\_identifier | Search for an entity by identifier or semantic. | body: identifier, entity\_type? |
| POST | /retrieve\_related\_entities | Retrieve related entities. | body: entity\_id, relationship\_types?, depth? |
| POST | /retrieve\_graph\_neighborhood | Retrieve the graph neighborhood. | body: node\_id, node\_type |
| POST | /entities/merge | Merge two entities. | body: source\_entity\_id, target\_entity\_id |
| POST | /delete\_entity | Delete an entity. | body: entity\_id |
| POST | /restore\_entity | Restore an entity. | body: entity\_id |
| GET | /sources | List sources. | query: limit?, offset? |
| GET | /sources/{id} | Get a source by ID. | path: id |
| GET | /observations | List observations. | query: limit?, offset? |
| POST | /observations/query | Query observations. | body: filters |
| POST | /observations/create | Create an observation. | body: entity\_id, fields |
| GET | /relationships | List relationships. | query: limit?, offset? |
| GET | /relationships/{id} | Get a relationship by ID. | path: id |
| POST | /relationships/snapshot | Get a relationship snapshot. | body: relationship\_key or ids |
| POST | /create\_relationship | Create a relationship. | body: relationship\_type, source\_entity\_id, target\_entity\_id |
| POST | /delete\_relationship | Delete a relationship. | body: relationship\_key |
| POST | /restore\_relationship | Restore a relationship. | body: relationship\_key |
| GET | /timeline | List timeline events. | query: type?, from?, to? |
| GET | /timeline/{id} | Get a timeline event by ID. | path: id |
| GET | /schemas | List schema types. | — |
| GET | /schemas/{entity\_type} | Get a schema for an entity type. | path: entity\_type |
| POST | /analyze\_schema\_candidates | Analyze schema candidates. | body: entity\_type, entity\_id? |
| POST | /get\_schema\_recommendations | Get schema recommendations. | body: entity\_type |
| POST | /update\_schema\_incremental | Update a schema incrementally. | body: entity\_type, new\_fields |
| POST | /register\_schema | Register a schema. | body: schema |
| POST | /store | Store structured entities. | body: entities, idempotency\_key?, relationships? |
| POST | /store/unstructured | Store an unstructured file. | body: file\_path or file\_content, mime\_type |
| POST | /correct | Submit a correction. | body: entity\_id, field, value |
| POST | /reinterpret | Reinterpret a source. | body: source\_id |
| GET | /interpretations | List interpretations. | query: limit?, offset? |
| GET | /stats | Get server stats. | — |
| GET | /server-info | Get server info. | — |
| POST | /health\_check\_snapshots | Run health check snapshots. | — |
| GET | /get\_file\_url (internal path) | Get a signed file URL (internal). | query: path |
|  | — | Parse a file into agent-readable text without storing. | \- |
|  | — | Check for a newer npm package version. | \- |
| GET | /health | Check if server is running. | — |
| GET | /openapi.yaml | Get OpenAPI spec for API documentation. | — |
|  | — | Initialize Neotoma (data dirs, DB, encryption, .env). | \- |
|  | — | Reset local Neotoma state to clean slate. | \- |
|  | — | Start, stop, or manage the API server. | \- |
|  | — | Configure or check MCP server entries in IDE configs. | \- |
|  | — | Check or install CLI agent instructions for IDEs. | \- |
|  | — | Stream record changes in real time. | \- |
|  | — | Show or change storage paths and merge databases. | \- |
|  | — | Create or restore a backup. | \- |
|  | — | Read persistent log files. | \- |
|  | — | Interactive session with persistent prompt. | \- |
|  | — | Run npm scripts from the repo. | \- |
|  | — | Interpret uninterpreted sources (backfill). | \- |
|  | — | Log out or get MCP auth token. | \- |

Scroll right

◆

## Error responses

All errors use a structured envelope:

{
  "error\_code": "INGESTION\_FILE\_TOO\_LARGE",
  "message": "File exceeds maximum size of 50MB",
  "details": { "file\_size": 52428800, "max\_size": 52428800 },
  "trace\_id": "trace-uuid",
  "timestamp": "2024-01-01T12:00:00Z"
}

Standard HTTP status codes: `200` OK, `201` Created, `400` Bad Request, `401` Unauthorized, `403` Forbidden, `404` Not Found, `409` Conflict, `413` Payload Too Large, `429` Rate Limited, `500` Internal Server Error, `503` Service Unavailable. Check `error_code` for programmatic handling, not just the HTTP status.

◆

## Pagination

List endpoints accept `limit` and `offset` parameters. Use `include_total_count: true` when building pagination UI. Recommended: keep `limit` at 100 or below for performance.

{
  "filters": { "entity\_type": "task" },
  "limit": 20,
  "offset": 0,
  "include\_total\_count": true
}

◆

## File operations

Upload files via `POST /upload_file` (multipart/form-data) or the unified `POST /store` with structured entities. File size limit: 50 MB. Retrieve signed URLs via `GET /get_file_url?file_path=...` (default expiry: 1 hour).

Continue with [MCP reference](/mcp), [CLI reference](/cli), [schema management](/schema-management), and [architecture](/architecture).