Knowledge API

TDocs API reference

TDocs stores durable, revisioned project knowledge. Updates use optimistic concurrency: always read the current page version and send it back as expectedVersion.

Canonical namespace/api/docs

The older Board-coupled Docs routes remain internal compatibility aliases; new clients should use this namespace.

All TDocs calls

Method	Path	Purpose
GET	`/api/docs/projects/:projectId/pages`	List pages; filter by kind/status.Docs read
POST	`/api/docs/projects/:projectId/pages`	Create a document, folder, or requirement.Docs write
GET	`/api/docs/projects/:projectId/pages/:pageId`	Read body, metadata, bindings, and revisions.Docs read
PATCH	`/api/docs/projects/:projectId/pages/:pageId`	Create the next immutable revision.Docs write
DELETE	`/api/docs/projects/:projectId/pages/:pageId`	Archive a page.Docs write
GET	`/api/docs/projects/:projectId/api-catalog`	List TSwagger definitions visible for typed linking.Docs read
POST	`/api/docs/projects/:projectId/pages/:pageId/api-bindings`	Link an API definition/version to a page.Docs write
PATCH	`/api/docs/projects/:projectId/pages/:pageId/api-bindings/:bindingId`	Change the optional version pin.Docs write
DELETE	`/api/docs/projects/:projectId/pages/:pageId/api-bindings/:bindingId`	Remove a typed API link.Docs write
GET	`/api/docs/projects/:projectId/pages/:pageId/requirement-review`	Read the requirement-review state.Docs read
POST	`/api/docs/projects/:projectId/pages/:pageId/requirement-review/messages`	Add review dialogue and recompute clarity.Docs write
POST	`/api/docs/projects/:projectId/pages/:pageId/requirement-review/approve`	Approve a ready requirement and create linked work.Docs write
GET	`/api/docs/ideas`	List the current user's personal ideas.Docs session/key
POST	`/api/docs/ideas`	Create a personal idea.Docs session/key
PATCH	`/api/docs/ideas/:ideaId`	Edit or archive a personal idea.Docs session/key

Create a page

POST /api/docs/projects/<projectId>/pages

{
  "title": "Payment callback integration",
  "kind": "document",
  "bodyMarkdown": "# Payment callback\n\nDecision and examples…",
  "status": "draft",
  "linkedWorkItemIds": ["<work-item-id>"],
  "authorType": "agent",
  "changeSummary": "Initial integration guide"
}

Kinds: document, folder, requirement. Statuses: draft, published, archived.

Update without overwriting another editor

GET /api/docs/projects/<projectId>/pages/<pageId>

PATCH /api/docs/projects/<projectId>/pages/<pageId>
{
  "expectedVersion": 14,
  "bodyMarkdown": "# Updated content…",
  "status": "published",
  "authorType": "agent",
  "changeSummary": "Document callback retry behavior"
}

If another editor already created version 15, the update returns 409 Conflict. Reload, merge intentionally, and retry with the new version; never increment blindly.

Link TDocs to TSwagger

POST /api/docs/projects/<projectId>/pages/<pageId>/api-bindings
{
  "apiDefinitionId": "<api-definition-id>",
  "apiVersionId": "<optional-version-id>"
}

The typed relationship survives title/URL changes and is visible from both TDocs and TSwagger. Omit apiVersionId to follow all/latest versions.