Stardust & search

Endpoints for creating, searching, and managing knowledge records.

Stardust

Prefer MCP for writes. Use memory.write or brain.think instead of POST /stardust — they run the full integration pipeline (entity extraction, graph linking, contradiction detection). The REST endpoint creates a raw record without integration.

GET /stardust/{id}

Full stardust record with metadata, entities, and backlinks.

POST /stardust

Create a raw stardust record.

curl -X POST http://localhost:8000/api/v1/stardust \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Always use UTC timestamps",
    "planet_name": "Engineering",
    "region": "procedural",
    "confidence": 0.95,
    "gravity": "GALAXY"
  }'

PUT /stardust/{id}

Update content, confidence, or tags.

DELETE /stardust/{id}

Soft-delete — sets valid_until to now. The record remains in the graph for history.

Search

GET /search

Semantic search with RRF fusion. Same engine as memory.search and brain.recall.

curl "http://localhost:8000/api/v1/search?query=database+decisions&planet=Engineering&limit=5"

Param	Required	Default	Description
query	Yes	—	Natural language search query
planet	No	All	Restrict to a planet
biome	No	All	Restrict to a biome
region	No	All	Restrict to a cognitive region
limit	No	5	Max results (max: 50)

Entities

GET /entities

List entities. Filters: planet_id, min_tier (1–3), limit.

GET /entities/{id}

Entity with relationships and backlinks.

PUT /entities/{id}

Update entity type or tier.

Contradictions

GET /contradictions

List contradictions. Filter: status (UNRESOLVED, RESOLVED).

POST /contradictions/{id}/resolve

Resolve a contradiction.

{"resolution": "supersede", "winner_id": "sd-123"}

Resolution	Effect
supersede	Winner keeps full confidence; loser gets valid_until set
coexist	Both preserved, tagged with context
synthesize	New record created from both; originals archived

Synthesis

POST /synthesis

LLM-powered synthesis of a topic. Returns current understanding, key decisions, open questions, and contradictions.

curl -X POST http://localhost:8000/api/v1/synthesis \
  -d '{"topic": "authentication", "include_open_questions": true, "max_tokens": 1000}'

Ask

POST /ask

Natural language question (same as brain.ask MCP tool). Routes to the appropriate graph or synthesis operation.

curl -X POST http://localhost:8000/api/v1/ask \
  -d '{"question": "What decisions were made about the database?", "planet": "Engineering"}'

Routing

GET /routing/inbox

Unrouted records in the Inbox Biome, each with a routing suggestion and confidence score.

POST /routing/inbox/{stardust_id}/route

Route an Inbox record to a Planet. Logs the correction for routing engine improvement.

curl -X POST "http://localhost:8000/api/v1/routing/inbox/sd-123/route?planet_name=Engineering"

GET /routing/stats

Routing accuracy: method breakdown, average confidence, correction rate per method.