Read-only API reference

Результат

Вы можете проверить актуальные request parameters и response schemas для небольшого reviewed набора read-only product endpoints без публикации administration, connector, OAuth, webhook и mutation routes.

Открыть generated OpenAPI document.

Граница support и authentication

Reference описывает endpoints, используемые authenticated clients Threadory. Это не general-purpose public REST integration contract:

• каждый project route требует short-lived human session JWT и доступ к указанному project;
• public docs не предоставляют token-issuance flow;
• bde_ API keys из Settings → API Keys предназначены для MCP и поддерживаемых plugin boundaries, а не этих management routes;
• для поддерживаемого external read access используйте MCP guide.

Если managed environment явно предоставляет approved REST client flow, передавайте его session JWT как Authorization: Bearer <session-jwt>. Не извлекайте token из browser storage, не вставляйте его в ticket и не commit скрипт с ним. Только GET /healthz в этом reference не требует authentication.

Base URL принадлежит environment. Не копируйте development или internal host name из примеров.

Опубликованные operations

Method	Path	Назначение
GET	/healthz	Проверить API process и audit-writer health
GET	/projects/{project_id}/entities	Получить entities с filters kind, source, retired-state, limit и offset
GET	/projects/{project_id}/entities/{entity_id}	Прочитать одну entity
GET	/projects/{project_id}/entities/{entity_id}/related	Получить явно связанные entities
GET	/projects/{project_id}/entities/{entity_id}/backlinks	Получить incoming links
GET	/projects/{project_id}/entities/{entity_id}/neighborhood	Прочитать bounded graph neighborhood
GET	/projects/{project_id}/decisions	Получить decisions с date, owner, confidence и limit filters
GET	/projects/{project_id}/action_items	Получить action items с date, owner, status и limit filters
GET	/projects/{project_id}/graph-health	Прочитать coverage, freshness, embedding, orphan и recommendation metrics
GET	/projects/{project_id}/people	Получить project people и action-item counts
GET	/projects/{project_id}/people/{person_id}/items	Получить action items одного person

project_id, entity_id и person_id имеют формат UUID. Collection endpoints ограничивают limit; проверяйте generated parameter schema, а не ожидайте unbounded response. Entity list по умолчанию исключает retired entities.

Result и обработка ошибок

Считайте fields в generated component schemas текущим allowlisted contract. Пустые descriptions оставлены намеренно: source docstrings, examples, callbacks, operation IDs, unused schemas и vendor extensions удаляются до публикации.

Типовые результаты:

Status	Значение	Безопасное действие
200	Request успешен	Проверьте response shape до использования fields
401	Session token отсутствует, invalid или expired	Войдите снова через supported product flow
403	У user нет доступа к project или operation	Запросите правильную project role; не используйте token другого user
404	Project или resource не виден	Проверьте IDs и project context
422	Path/query value не прошёл validation	Исправьте UUID, date, enum или pagination
429	Достигнут rate limit	Используйте backoff; не увеличивайте parallel requests

HTTP 200 от /healthz недостаточно, если body сообщает degraded audit writer. Проверяйте body.

Безопасность публикации

Downloadable schema генерируется из live FastAPI application через exact fail-closed allowlist. Новые routes никогда не публикуются автоматически. Generator также:

• удаляет raw optional Authorization header parameter и добавляет explicit bearer security scheme;
• удаляет descriptions, examples, callbacks, source operation IDs, external docs и vendor extensions;
• сохраняет только component schemas, достижимые из выбранных operations;
• отклоняет forbidden path families до записи artifact.

Исключены administrative organization/membership routes, API-key management, audit, cost/model settings, skills, approvals, connector configuration, OAuth, webhooks, export, reindex и другие mutation/operator endpoints.

Поддерживать актуальность

Из repository root:

make docs-openapi
make docs-openapi-check

Рассматривайте каждый generated diff как изменение API contract и security boundary. CI падает, если committed artifact устарел. Не добавляйте route в allowlist только потому, что он существует в FastAPI: сначала проверьте authorization, response fields, stability, rate limits и соответствие public product contract.