API Reference

Base path: /api/v1

Authentication: Authorization: Bearer <api_key> (or Token <api_key>). Dev mode can disable auth with AUTH_DISABLED=true.

POST /events

Ingest interaction events. This is the primary write path — append-only.

Request

{
  "space": "user:123",
  "events": [
    {
      "timestamp": "2026-02-28T10:05:12Z",
      "src": "user:123",
      "dst": "topic:car-buying",
      "type": "chat",
      "intensity": 2.0
    },
    {
      "timestamp": "2026-02-28T10:05:30Z",
      "src": "agent:planner",
      "dst": "tool:car-comparison",
      "type": "tool_use",
      "intensity": 1.0
    }
  ],
  "modulations": [
    {
      "entity": "topic:bikes",
      "attention": 0.1,
      "decay": 50
    }
  ]
}

Fields

Field	Type	Required	Description
`space`	string	Yes	Namespace for the events (e.g. `user:123`)
`events`	array	Yes	One or more interaction events
`events[].timestamp`	string	No	ISO 8601 timestamp. Defaults to server time if omitted.
`events[].src`	string	Yes	Source entity
`events[].dst`	string	Yes	Destination entity
`events[].type`	string	No	Event type label (e.g. `chat`, `tool_use`, `retrieval`)
`events[].intensity`	number	No	Signal strength. Default `1.0`. Higher values reinforce more.
`modulations`	array	No	Inline attention modulations (same as `/modulate`)

Response

204 No Content

GET /focus

Ranked items that matter now. This is the primary read path.

Parameters

Parameter	Type	Required	Description
`space`	string	Yes	Namespace to query
`k`	integer	No	Max items to return (default: 10)

Request

GET /api/v1/focus?space=user:123&k=5

Response

{
  "asOf": "2026-02-28T10:06:00Z",
  "items": [
    { "id": "topic:car-buying", "score": 0.83 },
    { "id": "topic:stroller", "score": 0.61 },
    { "id": "topic:cycling", "score": 0.22 }
  ]
}

Fields

Field	Type	Description
`asOf`	string	Timestamp of the snapshot
`items`	array	Ranked entities
`items[].id`	string	Entity identifier
`items[].score`	number	Attention score (0.0–1.0+)

GET /next

Ranked next hops from an entity. Shows likely associations.

Parameters

Parameter	Type	Required	Description
`space`	string	Yes	Namespace to query
`src`	string	Yes	Source entity to explore from
`k`	integer	No	Max items to return (default: 10)

Request

GET /api/v1/next?space=user:123&src=topic:car-buying&k=5

Response

{
  "asOf": "2026-02-28T10:06:00Z",
  "items": [
    { "id": "user:123", "score": 0.83 },
    { "id": "tool:car-comparison", "score": 0.45 },
    { "id": "topic:stroller", "score": 0.12 }
  ]
}

POST /pathways

Multi-hop associations via sampled walks. Discovers deeper connections between entities.

Request

{
  "space": "user:123",
  "start": "user:123",
  "k": 5,
  "mode": "deep"
}

Fields

Field	Type	Required	Description
`space`	string	Yes	Namespace to query
`start`	string	Yes	Starting entity for the walk
`k`	integer	No	Number of top entities/paths to return
`mode`	string	No	Exploration depth: `"fast"`, `"balanced"` (default), `"deep"`

Mode options

Mode	Description
`"fast"`	Fewer samples, shorter walks — low latency
`"balanced"`	Good default (used when mode is omitted)
`"deep"`	More samples, longer walks — thorough

Response

{
  "asOf": "2026-02-28T10:06:00Z",
  "topEntities": [
    { "id": "topic:car-buying", "score": 0.72 },
    { "id": "brand:toyota", "score": 0.51 },
    { "id": "model:yaris_cross", "score": 0.44 }
  ],
  "paths": [
    {
      "nodes": ["user:123", "topic:car-buying", "brand:toyota", "model:yaris_cross"],
      "score": 0.34
    },
    {
      "nodes": ["user:123", "topic:car-buying", "doc:comparison_guide"],
      "score": 0.28
    }
  ]
}

Fields

Field	Type	Description
`topEntities`	array	Most relevant entities found across walks
`paths`	array	Sampled paths through the attention graph
`paths[].nodes`	array	Ordered list of entities in the path
`paths[].score`	number	Path relevance score

POST /modulate

Suppress or amplify entity attention. Modulation adjusts how much an entity appears in query results without erasing its memory.

Request

{
  "space": "user:123",
  "modulations": [
    { "entity": "topic:bikes", "attention": 0.1, "decay": 50 },
    { "entity": "topic:math", "attention": 3.0, "decay": 50 }
  ]
}

Fields

Field	Type	Required	Description
`space`	string	Yes	Namespace
`modulations`	array	Yes	One or more modulation directives
`modulations[].entity`	string	Yes	Entity to modulate
`modulations[].attention`	number	Yes	Multiplier for attention score
`modulations[].decay`	integer	No	Events until modulation fades to half strength. Omit for persistent.

Attention values

Value	Effect
`0.0`	Fully suppress — entity disappears from results
`0.1`	Strongly suppress — 10% of normal
`1.0`	Normal (resets any modulation)
`3.0`	Triple the score

Response

204 No Content

Modulations can also be sent inline with events via the modulations field in POST /events.