Document the read_document_history context action

SI
5d ago
+46-2

Summary

Documents the new read_document_history action of the shared POST /api/context operation:

  • Request variant. document_id, optional organization_id, a before_revision cursor (1 or more), and limit (1–100). document_id comes from a brief or saved-brief response, either documents[].id or input_manifest.documents[].documentId. The read action returns the request, not documents.
  • Example request.
  • Response contract. state, document, and newest-first versions. Each version has result_id, change, backfilled, recorded_at, result_status, evidence_kind, source_version_ids and source_state. The response also includes has_more and next_before.

This is the contract for resolving a superseded brief's cited document version to the result that was current at that revision. api-reference/context/operate.mdx stays frontmatter-only, and there is no nav change.

Refs recoupable/app#2121 (child of epic recoupable/app#2116).

Merge sequencing

Order: docs → database → api → app.

  • This PR is the contract and has no runtime effect.
  • Sibling PRs for this ticket: database recoupable/database#99 (migration + fixtures) and api recoupable/api#1004 (shared operation + MCP exposure).
  • database#99 is a draft: its production apply waits for the CE01 deployed-schema verification (recoupable/app#2117). The action works only once that migration is applied, so this contract should not be published ahead of it.
  • No app PR in this slice. Depends on no open PR.

Verification

  • python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses.
  • grep -c read_document_history api-reference/openapi/context.json → 4.
  • json.dumps(indent=2) round-trips the file byte-for-byte, so the diff contains only the additive variant, example and description text.
  • Schema bounds match the API zod schema: before_revision minimum 1; limit 1–100, default 50.
  • Red → green: not applicable (documentation only).
  • Not verified: hosted Mintlify render, hosted deployment, live providers, production database.

Out of scope / known gaps

  • No MDX page or docs.json change: the operate page is frontmatter-only by convention.
  • Correction/withdrawal workflows that would write new document revisions (#2124), broader lifecycle exposure (#2125), and a chat UI for lineage.

🤖 Generated with Claude Code