Developers · API reference

The REST API

Base URL: https://mcp.falkster.ai/api/v1 on our install. Every Heidi instance has its own base URL; yours ships with your workspace. Plain JSON in, plain JSON out.

Authentication

One header: Authorization: Bearer <token>. Tokens are minted in the admin Developer Portal. Each token carries its own scope set, and can be bound to a person so everything it reads respects that person’s permissions. The API is off until you create a token: before that, every call returns 503, not an open door.

First call

curl https://mcp.falkster.ai/api/v1/about \
  -H "Authorization: Bearer $HEIDI_API_TOKEN"

{"service": "heidi", "version": "…", "scopes": ["ask", "read"]}

Scopes and limits

Scope	Grants	Calls / min
`ask`	Free-form questions. A full agent turn: memory, tools, reasoning.	120
`read`	Memory search, entities, skills, agents, activity.	600
`write`	Mint facts and entities. Forget facts.	60
`tools`	Invoke tools directly, trigger agent runs.	120

Default grant is ask,read. Blow a limit and you get 429 with Retry-After and X-RateLimit-* headers, never a silent drop.

Ask

POST/api/v1/askask

The front door. Runs a full Heidi turn: memory recall, tools, reasoning. Body: {"prompt": "...", "principal": "optional@email"}. Returns {"answer": "..."} with sources woven in.

shell

curl https://mcp.falkster.ai/api/v1/ask \
  -H "Authorization: Bearer $HEIDI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Which customers mentioned SSO this quarter?"}'

Memory

POST/api/v1/memory/searchread

Hybrid search over the knowledge graph. Results carry text, kind, namespace, and source_url: every hit has a receipt.

shell

curl https://mcp.falkster.ai/api/v1/memory/search \
  -H "Authorization: Bearer $HEIDI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "EU data residency commitments", "k": 12}'

GET/api/v1/memory/entitiesread

The people, projects, and companies Heidi knows, most-active first. Filter with ?type=person, page with ?limit=.

GET/api/v1/memory/recentread

What Heidi learned lately: new facts and consolidation merges. ?minutes=1440 by default. Perfect for a morning digest bot.

POST/api/v1/memory/factswrite

Teach the brain from your own systems. New facts land with provenance and go through the same hygiene pipeline as everything else.

shell

curl https://mcp.falkster.ai/api/v1/memory/facts \
  -H "Authorization: Bearer $HEIDI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Acme renewal signed 2026-07-30, 2-year term."}'

POST/api/v1/memory/entitieswrite

Create an entity (a customer, a project, a system) so facts have something to attach to.

POST/api/v1/memory/facts/{id}/forgetwrite

Make her forget. The fact is retired with the reason on record: memory stays under your control.

Tools and agents

GET/api/v1/toolsread

Every tool Heidi can call, with descriptions and input schemas. The same registry her chat uses.

POST/api/v1/tools/{name}tools

Invoke one tool directly with JSON args. Only read-only, side-effect-free tools are allowed on this raw path (memory reads, catalogs, web search). Anything that changes the world routes through /ask, where confirmation gating runs.

GET/api/v1/agentsread

The scheduled workflow agents and their cadence.

POST/api/v1/agents/{id}/runtools

Trigger one agent run now. Synchronous; returns the run result.

GET/api/v1/activityread

The unified activity feed: what Heidi has been doing. Filter with ?kind=.

Discovery

GET/api/v1any token

Capability discovery: the endpoint catalog, your scopes, and the MCP endpoint. Docs that cannot drift, because the server generates them from the same table this page is written from.

GET/api/v1/aboutany token

Version, build, and the scopes your token holds. The cheap first call.

GET/api/v1/mcp/discoveryany token

The MCP capability descriptor: endpoint URL, protocol version, auth scheme, tool counts, rate limits. Works without a token, so clients can bootstrap.

Ready to make your first call?

Your instance ships with the Developer Portal to mint scoped tokens. Or try the playground right now, no key needed.

Open the playground

Answers →

Ask AI about Heidi: