Read-only API reference

Outcome

You can inspect the current request parameters and response schemas for a small, reviewed set of read-only product endpoints without exposing administration, connector, OAuth, webhook, or mutation routes.

Open the generated OpenAPI document.

Support and authentication boundary

This reference describes endpoints used by authenticated Threadory product clients. It is not a general-purpose public REST integration contract:

• every project route requires a short-lived human session JWT and access to the specified project;
• the public docs do not provide a token-issuance flow;
• bde_ API keys created in Settings → API Keys are for MCP and supported plugin boundaries, not these management routes;
• for supported external read access, use the MCP guide.

If your managed environment explicitly provides an approved REST client flow, send its session JWT as Authorization: Bearer <session-jwt>. Never extract a token from browser storage, paste it into a ticket, or commit it to a script. GET /healthz is the only operation in this reference that does not require authentication.

The base URL is environment-owned. Do not assume a development or internal host name from examples.

Published operations

Method	Path	Purpose
GET	/healthz	Check API process and audit-writer health
GET	/projects/{project_id}/entities	List project entities with kind, source, retired-state, limit, and offset filters
GET	/projects/{project_id}/entities/{entity_id}	Read one entity
GET	/projects/{project_id}/entities/{entity_id}/related	List explicitly related entities
GET	/projects/{project_id}/entities/{entity_id}/backlinks	List incoming links
GET	/projects/{project_id}/entities/{entity_id}/neighborhood	Read the bounded graph neighborhood
GET	/projects/{project_id}/decisions	List decisions with date, owner, confidence, and limit filters
GET	/projects/{project_id}/action_items	List action items with date, owner, status, and limit filters
GET	/projects/{project_id}/graph-health	Read coverage, freshness, embedding, orphan, and recommendation metrics
GET	/projects/{project_id}/people	List project people and action-item counts
GET	/projects/{project_id}/people/{person_id}/items	List one person's action items

project_id, entity_id, and person_id are UUIDs. Collection endpoints cap their limit; inspect the generated parameter schema instead of assuming an unbounded response. By default, the entity list excludes retired entities.

Result and error handling

Treat response fields in the generated component schemas as the current allowlisted contract. Empty descriptions are intentional: source docstrings, examples, callbacks, operation IDs, unused schemas, and vendor extensions are removed before publication.

Common outcomes:

Status	Meaning	Safe response
200	Request succeeded	Validate the response shape before using fields
401	Session token is missing, invalid, or expired	Sign in again through the supported product flow
403	The user cannot access the project or operation	Request the correct project role; do not reuse another user's token
404	Project or resource is not visible	Recheck IDs and project context
422	Path or query value failed validation	Correct UUID, date, enum, or pagination values
429	Rate limit was reached	Back off and retry; do not parallelize more requests

An HTTP 200 from /healthz is not enough when its body reports a degraded audit writer. Check the body.

Publication safety

The downloadable schema is generated from the live FastAPI application through an exact, fail-closed allowlist. New routes are never published automatically. The generator also:

• removes the raw optional Authorization header parameter and replaces it with an explicit bearer security scheme;
• removes descriptions, examples, callbacks, source operation IDs, external docs, and vendor extensions;
• retains only component schemas reachable from the selected operations;
• rejects forbidden path families before writing the artifact.

Administrative organization/membership routes, API-key management, audit, cost/model settings, skills, approvals, connector configuration, OAuth, webhooks, export, reindex, and other mutation or operator endpoints are excluded.

Keep it current

From the repository root:

make docs-openapi
make docs-openapi-check

Review every generated diff as an API contract and security-boundary change. CI fails when the committed artifact is stale. Do not add a route to the allowlist only because it exists in FastAPI; first review authorization, response fields, stability, rate limits, and whether it belongs in the public product contract.