Neotoma

API and OpenAPI specification

The Neotoma REST API is defined in the OpenAPI spec. 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.

Minimal request examples

# Store structured entities
curl -X POST http://localhost:3080/store \
  -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 "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 "Content-Type: application/json" \
  -d '{"entity_id":"<entity_id>"}'

Authentication requirements differ by endpoint and deployment mode. Local development workflows often run without OAuth while hosted or shared environments should enforce authenticated access.

MethodEndpointDescriptionParameters
GET/meGet the current user.—
POST/mcp/oauth/initiateInitiate the OAuth flow.body: auth_provider, redirect_uri
GET/mcp/oauth/authorizeHandle the OAuth authorize redirect.query: code, state
POST/mcp/oauth/tokenExchange the OAuth code for a token.body: code, code_verifier
GET/mcp/oauth/statusGet OAuth connection status.—
GET/mcp/oauth/connectionsList OAuth connections.—
DELETE/mcp/oauth/connections/{id}Remove an OAuth connection.path: id
POST/entities/queryQuery entities with filters.body: filters, limit, offset
GET/entities/{id}Get an entity by ID.path: id
POST/get_entity_snapshotGet an entity snapshot with provenance.body: entity_id, at?
GET/entities/{id}/observationsList observations for an entity.path: id
POST/list_observationsList observations by query.body: filters
POST/get_field_provenanceGet provenance for a field.body: entity_id, field
GET/entities/{id}/relationshipsList relationships for an entity.path: id
POST/list_relationshipsList relationships by query.body: filters
POST/retrieve_entity_by_identifierSearch for an entity by identifier or semantic.body: identifier, entity_type?
POST/retrieve_related_entitiesRetrieve related entities.body: entity_id, relationship_types?, depth?
POST/retrieve_graph_neighborhoodRetrieve the graph neighborhood.body: node_id, node_type
POST/entities/mergeMerge two entities.body: source_entity_id, target_entity_id
POST/delete_entityDelete an entity.body: entity_id
POST/restore_entityRestore an entity.body: entity_id
GET/sourcesList sources.query: limit?, offset?
GET/sources/{id}Get a source by ID.path: id
GET/observationsList observations.query: limit?, offset?
POST/observations/queryQuery observations.body: filters
POST/observations/createCreate an observation.body: entity_id, fields
GET/relationshipsList relationships.query: limit?, offset?
GET/relationships/{id}Get a relationship by ID.path: id
POST/relationships/snapshotGet a relationship snapshot.body: relationship_key or ids
POST/create_relationshipCreate a relationship.body: relationship_type, source_entity_id, target_entity_id
POST/delete_relationshipDelete a relationship.body: relationship_key
POST/restore_relationshipRestore a relationship.body: relationship_key
GET/timelineList timeline events.query: type?, from?, to?
GET/timeline/{id}Get a timeline event by ID.path: id
GET/schemasList schema types.—
GET/schemas/{entity_type}Get a schema for an entity type.path: entity_type
POST/analyze_schema_candidatesAnalyze schema candidates.body: entity_type, entity_id?
POST/get_schema_recommendationsGet schema recommendations.body: entity_type
POST/update_schema_incrementalUpdate a schema incrementally.body: entity_type, new_fields
POST/register_schemaRegister a schema.body: schema
POST/storeStore structured entities.body: entities, idempotency_key?, relationships?
POST/store/unstructuredStore an unstructured file.body: file_path or file_content, mime_type
POST/correctSubmit a correction.body: entity_id, field, value
POST/reinterpretReinterpret a source.body: source_id
GET/interpretationsList interpretations.query: limit?, offset?
GET/statsGet server stats.—
GET/server-infoGet server info.—
POST/health_check_snapshotsRun health check snapshots.—
GET/get_file_url (internal path)Get a signed file URL (internal).query: path

Continue with schema management, data model walkthrough, and architecture.