API.md

HTTP API

Chitraq serves 64 routes over HTTP, on 127.0.0.1:4317 by default. This file is generated from the table the server dispatches on, so it cannot describe a route that does not exist or miss one that does.

node src/server/serve.js          # or: npm start

Authentication

Credentials are required once an account exists, and not before — a fresh install reached from the machine it runs on answers everything. Serving a non-loopback address with no account is refused at startup; see SECURITY.md.

Two kinds of credential, both as Authorization: Bearer <value>:

• A session token from POST /api/auth/login, which is a person.
• An access token from chitraq tokens --new <name>, which is a program. It starts ctq_ and is shown once.

An access token narrows: presenting one restricts the caller to its scope even where an anonymous caller would be allowed more. So a side project can hold something that genuinely cannot erase anything.

Scope	Can reach
read	read routes
write	read and write routes
admin	everything, including keys, tokens, export and erasure

Three routes need no credential at all, so that signing in is possible: GET /api/health, GET /api/auth/status, POST /api/auth/login.

Client library

src/client.js is a dependency-free class for calling all of this from another project, and is the recommended way in.

import { ChitraqClient } from 'chitraq/client';

const memory = new ChitraqClient({
  url: 'http://127.0.0.1:4317',
  token: process.env.CHITRAQ_TOKEN,
});

await memory.remember({ title: 'Chose SQLite because it needs no server' });
const hits = await memory.search('sqlite');
const answer = await memory.ask('why did we drop the redis cache');

It throws ChitraqUnreachable when the memory cannot be reached and ChitraqError when it answers with a refusal — a distinction worth having, because one is worth retrying and the other never is.

Routes

System

Route	Scope
GET /api/health	read	Is this memory up, and which workspace is it.
GET /api/stats	read	Counts of everything held, plus operational health.
GET /api/capabilities	read	Which intelligence capabilities have a provider, and which are on the deterministic floor.
POST /api/policy	admin	Change what Chitraq is allowed to use: local only, remote, paid.
GET /api/intelligence-log	read	Every call made to a provider, with latency and cost.
POST /api/reindex	write	Rebuild every derived index from the objects. Safe; slow.
GET /api/export	admin	The entire workspace as JSON. Everything, including what was archived.
POST /api/import	admin	Merge a Chitraq export into this memory.

Capture

Route	Scope
POST /api/remember	write	Capture a note. Needs at least title.
POST /api/ingest	write	Capture a document: text, PDF, HTML, CSV, JSON, image, audio.

Retrieval

Route	Scope
GET /api/search	read	Search memory. Supports kind:, after:, quoted phrases and -exclude.
POST /api/ask	read	Ask a question. Quotes your own words when it can, escalates only when it cannot.
GET /api/answer-cache	read	How much the answer cache is holding and saving.
DELETE /api/answer-cache	write	Empty the answer cache.
GET /api/timeline	read	What happened, most recent first.
GET /api/events	read	The audit log: what changed, when, and by what.

Knowledge objects

Route	Scope
GET /api/objects	read	List Knowledge Objects, filterable by kind, origin and date.
GET /api/objects/:id	read	One object with its history, links, evidence and provenance.
PATCH /api/objects/:id	write	Correct an object. The previous version is kept, not overwritten.
POST /api/objects/:id/confirm	write	Mark knowledge as checked by a person.
POST /api/objects/:id/archive	write	Remove from retrieval, keeping the history.
POST /api/objects/:id/supersede	write	Replace one object with another, recording which replaced which.
POST /api/objects/:id/enrich	write	Ask intelligence for entities, keywords and attributes on this object.
POST /api/objects/:id/relate	write	Ask intelligence to propose relationships from this object.
DELETE /api/objects/:id	admin	Irreversibly destroy an object and its history. Only the fact of erasure remains.
GET /api/objects/:id/notices	read	Things worth knowing about this object without asking.

Relationships

Route	Scope
GET /api/graph	read	The relationship graph, from a starting point outwards.
POST /api/relations	write	Assert a relationship between two objects.
DELETE /api/relations/:id	write	Remove a relationship.

Proposals

Route	Scope
GET /api/proposals	read	Everything intelligence has suggested and is waiting on a decision for.
POST /api/proposals/:id/accept	write	Accept a proposal into memory.
POST /api/proposals/:id/reject	write	Decline a proposal. It is kept, marked rejected.
POST /api/proposals/bulk	write	Accept or reject many proposals at once, by filter or confidence.
POST /api/proposals/expire	write	Expire proposals that have sat undecided too long.

Conflicts

Route	Scope
GET /api/conflicts	read	Disagreements Chitraq has noticed between things it holds.
POST /api/conflicts/:id/resolve	write	Record which side of a disagreement is right, and why.

Entities and concepts

Route	Scope
GET /api/entities	read	People, places, products and projects found across your notes.
GET /api/entities/:id	read	One entity, with everything that mentions it.
GET /api/concepts	read	Ideas that recur across your notes.
POST /api/concepts/propose	write	Look for new recurring ideas and propose them.
GET /api/entities-duplicates	read	Entities that look like the same thing under two names.
POST /api/entities/:id/merge	write	Merge two entities into one, keeping both names as aliases.
POST /api/entities/:id/alias	write	Add another name for an entity.

Awareness and cost

Route	Scope
GET /api/notices	read	Things worth knowing without having asked.
GET /api/costs	read	What intelligence has cost, by provider and capability.
POST /api/budget	admin	Set what Chitraq may spend.

Sync

Route	Scope
GET /api/sync/changes	admin	Changes since a cursor, for another Chitraq to apply.
POST /api/sync/apply	admin	Apply changes sent by another Chitraq.
GET /api/sync/peers	read	Machines this memory has exchanged changes with.

Vector index

Route	Scope
POST /api/vector-index/build	write	Build the approximate vector index.
POST /api/vector-index/benchmark	read	Measure what the approximate index costs in recall and saves in time.

Accounts

Route	Scope
GET /api/auth/status	read	Whether authentication is on, and how many accounts exist. Public.
POST /api/auth/login	write	Sign in and receive a session token. Public.
POST /api/auth/logout	admin	End a session.
GET /api/auth/sessions	admin	Sessions currently signed in.

Access tokens

Route	Scope
GET /api/tokens	admin	Tokens issued to other programs. The token itself is never shown again.
POST /api/tokens	admin	Mint a scoped token for another program.
DELETE /api/tokens/:id	admin	Stop a token working, keeping the record that it existed.

Provider keys

Route	Scope
GET /api/keys	admin	Which provider keys are stored, and whether they are readable. Never the keys.
POST /api/keys/unlock	admin	Unlock stored keys for this process.
POST /api/keys/relock	admin	Make stored keys unreadable again without restarting.
POST /api/keys/lock	admin	Put a passphrase over stored keys.
POST /api/keys	admin	Store a provider API key, encrypted at rest.
DELETE /api/keys/:provider	admin	Forget a stored provider key.

Errors

Every failure is JSON with error and kind:

Status	Means
401	No credential, and this memory has accounts.
403	The token is real but scoped below what this route needs. The body says which scope it holds and which it needed.
404	No such route, or no such object.
400	The request was understood and refused. The message says why.