REST API

https://api.engram.unbidden.ai/v1

http://localhost:8000/v1

Authorization: Bearer YOUR_API_KEY

export ENGRAM_API_KEY=your-secret-key

Returns server status and version. No auth required.

// Response
{ "status": "ok", "version": "0.1.0" }

List all projects with node and edge counts.

// Response
[
  { "name": "my-project", "node_count": 142, "edge_count": 89 },
  ...
]

Create a new project (idempotent — safe to call if it already exists). Returns 201 on creation.

// Response
{ "project": "my-project", "created": true }

Return node and edge counts, broken down by node type.

// Response
{
  "project": "my-project",
  "node_count": 142,
  "edge_count": 89,
  "type_counts": {
    "decision": 34,
    "implementation": 28,
    "constraint": 19,
    "preference": 15,
    ...
  }
}

Retrieve the most relevant facts for a task description. Returns formatted markdown ready for injection into an AI context window.

POST /v1/projects/my-project/query
Content-Type: application/json

{
  "task": "what auth approach did we decide on?",
  "hops": 3,
  "top_k": 25
}

// Response
{
  "markdown": "## Decisions\n\n**Use JWT with short-lived access tokens...**\n\n...",
  "nodes_returned": 8,
  "total_nodes": 142,
  "tokens_estimated": 412
}

Field	Type	Default	Description
task	string	required	Natural-language task description or question
hops	integer	3	Graph traversal depth
top_k	integer	25	Maximum number of nodes to return

Extract structured facts from text and merge into the project graph. Text is automatically chunked when it exceeds 20,000 characters. Maximum input: 200,000 characters per request.

POST /v1/projects/my-project/extract
Content-Type: application/json

{
  "text": "We decided to use Postgres instead of SQLite for production because of concurrency requirements. Migration must happen before the July release.",
  "source_name": "session-2026-04-24",
  "verify": false
}

// Response
{
  "project": "my-project",
  "nodes_extracted": 2,
  "edges_extracted": 1,
  "nodes_per_1k_chars": 1.8,
  "avg_tags_per_node": 3.5
}

Field	Type	Default	Description
text	string	required	Raw text to extract facts from
source_name	string	"api"	Label for the source (e.g. "session-2026-04-24")
verify	boolean	false	Run a second verification pass to catch missed facts
chunk_size	integer	null (auto)	Force a specific chunk size in characters. Null = auto-detect.

Export the full project graph as markdown. Use this to copy memory into a context window, create backups, or migrate between instances.

Return account tier, usage, and rate limits for the authenticated API key. Requires authentication.

// Response
{
  "tier": "pro",
  "email": "you@example.com",
  "node_count": 4821,
  "project_count": 3,
  "rate_limits": {
    "requests_per_minute": 60,
    "requests_per_day": 5000
  }
}

Field	Type	Description
tier	string	Plan tier: free, pro, team, or local
email	string | null	Email address associated with the API key
node_count	integer	Total nodes across all your projects
project_count	integer	Number of projects on your account
rate_limits	object	requests_per_minute and requests_per_day for your tier

http://localhost:8000/docs