HTTP API Reference

YantrikDB Server exposes a JSON HTTP gateway on port 7438 (configurable). Every endpoint accepts a Bearer token in the Authorization header.

Authentication

Two ways to authenticate:

1. Per-database token — generated with yantrikdb token create --db <name>. Each token grants access to one database.
2. Cluster master token — when clustering is enabled, the cluster_secret doubles as a master token that works on any node and grants access to the default database.

curl -H "Authorization: Bearer ydb_xxxxxxxx..." http://localhost:7438/v1/stats

Endpoints

Memory operations

Method	Path	Description
POST	/v1/remember	Store a memory
POST	/v1/recall	Semantic search
POST	/v1/forget	Tombstone a memory
POST	/v1/relate	Create knowledge graph edge

POST /v1/remember

curl -X POST http://localhost:7438/v1/remember \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice leads engineering at Acme",
    "importance": 0.9,
    "domain": "work",
    "memory_type": "semantic",
    "valence": 0.0,
    "half_life": 168.0
  }'

Response: {"rid": "019d623a-..."}

Optional fields: metadata (object), namespace, certainty, source, emotional_state, embedding (pre-computed vector for client_only mode).

POST /v1/recall

curl -X POST http://localhost:7438/v1/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "who leads engineering?",
    "top_k": 5,
    "domain": "work",
    "expand_entities": true
  }'

Response:

{
  "results": [
    {
      "rid": "019d623a-...",
      "text": "Alice leads engineering at Acme",
      "score": 1.41,
      "memory_type": "semantic",
      "domain": "work",
      "importance": 0.9,
      "why_retrieved": ["semantically similar (0.54)", "important", "recent"]
    }
  ],
  "total": 1
}

POST /v1/forget

curl -X POST http://localhost:7438/v1/forget \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rid": "019d623a-..."}'

Response: {"rid": "...", "found": true}

POST /v1/relate

curl -X POST http://localhost:7438/v1/relate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "Alice",
    "target": "Acme",
    "relationship": "works_at",
    "weight": 1.0
  }'

Response: {"edge_id": "019d623a-..."}

Sessions

Method	Path	Description
POST	/v1/sessions	Start a cognitive session
DELETE	/v1/sessions/{id}	End a session

curl -X POST http://localhost:7438/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "chat-1", "client_id": "user-42"}'

Cognition

Method	Path	Description
POST	/v1/think	Run consolidation + conflict scan
GET	/v1/conflicts	List open conflicts
POST	/v1/conflicts/{id}/resolve	Resolve a conflict
GET	/v1/personality	Get derived personality traits

Info

Method	Path	Description
GET	/v1/health	Server health + cluster status (no auth required)
GET	/v1/stats	Engine statistics for the authenticated database
GET	/metrics	Prometheus-format metrics (no auth)

GET /v1/health

{
  "status": "ok",
  "engines_loaded": 1,
  "cluster": {
    "node_id": 1,
    "role": "Leader",
    "term": 5,
    "leader": 1,
    "accepts_writes": true,
    "healthy": true
  }
}

GET /metrics

Prometheus exposition format. Drops in to your existing scraping setup:

# HELP yantrikdb_active_memories Number of active memories
# TYPE yantrikdb_active_memories gauge
yantrikdb_active_memories{db="default"} 1247

# HELP yantrikdb_cluster_is_leader Whether this node is currently the leader
# TYPE yantrikdb_cluster_is_leader gauge
yantrikdb_cluster_is_leader{node_id="1"} 1

Database management

Method	Path	Description
GET	/v1/databases	List databases
POST	/v1/databases	Create a database

Cluster

Method	Path	Description
GET	/v1/cluster	Detailed cluster status
POST	/v1/cluster/promote	Manually promote this node to leader (force election)

GET /v1/cluster

{
  "clustered": true,
  "node_id": 1,
  "role": "Leader",
  "current_term": 5,
  "leader_id": 1,
  "healthy": true,
  "accepts_writes": true,
  "quorum_size": 2,
  "peers": [
    {
      "node_id": 2,
      "addr": "192.168.1.2:7440",
      "role": "voter",
      "reachable": true,
      "current_term": 5,
      "last_seen_secs_ago": 0.5
    },
    {
      "node_id": 99,
      "addr": "192.168.1.3:7440",
      "role": "witness",
      "reachable": true,
      "current_term": 5,
      "last_seen_secs_ago": 0.6
    }
  ]
}

Error responses

All errors return JSON with HTTP status:

{
  "error": "read-only: not the leader (current leader: node 2)",
  "leader": 2
}

Status	Meaning
200	Success
400	Invalid request body
401	Missing or invalid Bearer token
404	Database or memory not found
503	This node is read-only (not the leader) — try the leader
500	Internal server error