HTTP API

Start the Server

allsource-prime --mode http --port 3905 --data-dir ~/.prime/memory

The server binds to 0.0.0.0:3905 by default. All data is persisted to the specified data directory.

Create a Node

POST /api/v1/prime/nodes

curl -X POST http://localhost:3905/api/v1/prime/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "name": "Alice",
    "domain": "engineering",
    "properties": {
      "role": "Lead Engineer",
      "started": "2026-01"
    }
  }'

{
  "id": "node_a1b2c3d4",
  "type": "person",
  "name": "Alice",
  "domain": "engineering",
  "properties": { "role": "Lead Engineer", "started": "2026-01" },
  "created_at": "2026-03-22T10:00:00Z"
}

Get a Node

GET /api/v1/prime/nodes/:id

curl http://localhost:3905/api/v1/prime/nodes/node_a1b2c3d4

{
  "id": "node_a1b2c3d4",
  "type": "person",
  "name": "Alice",
  "domain": "engineering",
  "properties": { "role": "Lead Engineer", "started": "2026-01" },
  "created_at": "2026-03-22T10:00:00Z"
}

Delete a Node

DELETE /api/v1/prime/nodes/:id

curl -X DELETE http://localhost:3905/api/v1/prime/nodes/node_a1b2c3d4

{ "deleted": true, "id": "node_a1b2c3d4" }

Deletes are soft — the node is removed from the active graph but preserved in the event history.

Create an Edge

POST /api/v1/prime/edges

curl -X POST http://localhost:3905/api/v1/prime/edges \
  -H "Content-Type: application/json" \
  -d '{
    "source": "node_a1b2c3d4",
    "target": "node_e5f6g7h8",
    "relation": "leads"
  }'

{
  "source": "node_a1b2c3d4",
  "target": "node_e5f6g7h8",
  "relation": "leads",
  "created_at": "2026-03-22T10:01:00Z"
}

Get Neighbors

GET /api/v1/prime/nodes/:id/neighbors

curl http://localhost:3905/api/v1/prime/nodes/node_a1b2c3d4/neighbors

{
  "neighbors": [
    {
      "node": { "id": "node_e5f6g7h8", "type": "project", "name": "Prime" },
      "relation": "leads",
      "direction": "outgoing"
    }
  ],
  "count": 1
}

Hybrid Recall

POST /api/v1/prime/recall — combines vector similarity, graph expansion, and temporal recency.

curl -X POST http://localhost:3905/api/v1/prime/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who leads the Prime project?",
    "top_k": 5
  }'

{
  "results": [
    {
      "node": { "id": "node_a1b2c3d4", "type": "person", "name": "Alice" },
      "score": 0.92,
      "context": [
        { "relation": "leads", "target": "Prime" }
      ]
    }
  ],
  "query": "Who leads the Prime project?"
}

Compressed Index

GET /api/v1/prime/index — returns the auto-generated markdown knowledge map.

curl http://localhost:3905/api/v1/prime/index

{
  "index": "# Knowledge Index\n_2 nodes, 1 domain_\n\n## engineering\n- **Nodes:** 2 (person, project)\n- **Examples:** Alice, Prime",
  "node_count": 2,
  "domain_count": 1
}

Combined Context

POST /api/v1/prime/context — recall + index scaffolding for cross-domain questions.

curl -X POST http://localhost:3905/api/v1/prime/context \
  -H "Content-Type: application/json" \
  -d '{ "query": "How does engineering relate to revenue?" }'

{
  "index_excerpt": "## engineering\n- ...",
  "recall_results": [...],
  "cross_references": [
    { "from_domain": "engineering", "to_domain": "revenue", "edges": 3 }
  ]
}

Graph Stats

GET /api/v1/prime/stats

curl http://localhost:3905/api/v1/prime/stats

{
  "nodes": 42,
  "edges": 67,
  "domains": ["engineering", "product", "revenue"],
  "vectors": 128,
  "events_total": 312
}

Health Check

GET /health

curl http://localhost:3905/health

{ "status": "ok" }

Note: the health endpoint is at the root path, not under /api/v1/.

CORS Configuration

The HTTP server enables CORS for all origins by default in development. For production, set the PRIME_CORS_ORIGINS environment variable to a comma-separated list of allowed origins:

PRIME_CORS_ORIGINS="https://app.example.com,https://admin.example.com" \
  allsource-prime --mode http --port 3905 --data-dir /data/prime