TheoremBase Protocols

This page is the normative content contract for TheoremBase.

Scope

These protocols apply to theorem, definition, and proof content added through the UI or API.

Theorem and Proof Content

• Correctness and completeness are the author's responsibility.
• Statements must be precise and use explicit assumptions.
• Every nontrivial term used in a statement or proof must be defined locally or referenced explicitly.
• Every symbolic parameter appearing in a statement or proof should be introduced explicitly.
• Any content drawn from an external source must have a citation.
• Copied or adapted internal TheoremBase content should also carry a citation or attribution note that makes the source version explicit.
• Every nontrivial term or dependency must be referenced inline with \ref{...}, \eqref{...}, or \reftext{...}{...}. There is no separate "ambient" dependency list; if something is in the dependency chain it must appear in the statement or proof body. (The former additional_ref_labels field has been removed; older published versions created with it should gain inline references when revised.)
• \ref{}, \eqref{}, and \reftext{}{} are processed before the math renderer and must appear in prose only. They do not work inside any math environment ($...$, \[...\], \(...\), $$...$$). To link a symbol that appears in math, introduce the reference in surrounding prose (e.g., "…for every \reftext{def:natural-numbers-2026a}{natural number} $m$…"), then use the plain symbol in the math expression.
• \textbf{...}, \textit{...}, and \emph{...} are supported prose-formatting commands rendered as bold or italic. Use them freely in prose. \reftext{}{} and inline math ($...$) may appear inside them. Do not use \textbf or \textit inside math environments; use \mathbf or \mathit there instead.
• Use ref_label only for published, stable references.
• You may use draft_ref_label on theorem drafts when other drafts need to reference them before publish.
• Keep math and prose notation consistent.
• Avoid notation shifts inside a proof unless the new notation is defined or referenced.
• If a standard operation or notation is used, either reference its definition explicitly or treat it as approved ambient background under a documented policy.
• Ambient notation or operations are allowed only when their definitions or governing statements already lie in the item's dependency chain via inline references or upstream dependencies.
• If notation is used in a form that goes beyond the exact statement in which it was introduced, then the extension principle that makes that usage unambiguous should also lie in the dependency chain. Typical examples are iterated binary operations and reordered products.
• Do not create a second draft theorem or proof for the same target unless the earlier draft is intentionally being replaced or split.
• A later, more general theorem does not by itself make an earlier special-case theorem obsolete.

API Rules

• Use API endpoints for theorem, proof, citation, collaboration, and moderation workflows.
• Do not read or write theorem, proof, citation, comment, feedback, or review content directly in the database.
• Use Alembic migrations only for schema and static bootstrap data.

Attribution

• Copied or adapted content must be cited explicitly.
• Citation notes should distinguish adaptation from verbatim copying when relevant.
• Do not represent copied material as original work.
• If content is copied from an existing TheoremBase theorem or proof version into a new draft, preserve or refine the suggested attribution before publish.

Collaboration

• For an existing theorem or proof, revise the existing draft object unless you are intentionally creating a separate replacement or branch.
• Any author on a draft may publish it and manage collaborators.
• The primary author remains the canonical first author unless authorship is revised explicitly.
• Collaborator additions should use invitation and acceptance flows so coauthorship is confirmed by the invitee before authorship changes.

Versioning, Validation And Publish

• A theorem or proof object has one collaborator set at the parent-object level, and published versions inherit that authorship display.
• Drafts are for work in progress. Publish only when the content is acceptable as a public version.
• Validation is advisory. It helps detect structural problems but does not replace mathematical review or exposition review.
• Strict publish should be used when you expect all references to resolve to published labels.
• Draft-only references are acceptable in draft workflows but should not remain for strict publish.
• Publish with a clear, specific reason.
• A corrected replacement should be published before the superseded public version is redacted.
• Each ref_label is globally unique across all published versions of all theorems. A corrected or updated version must use a new label, typically by incrementing the letter suffix (e.g., 2026a → 2026b). After publishing the replacement, redact the prior version.

Review

• Use verify only for complete, rigorous proofs.
• Use flag comments on theorem versions or proof versions for major logical gaps, incorrect inferences, theorem/proof mismatch, or materially incorrect claims.
• Theorem version statements may be flagged, but they are not subject to verify.

Content Workflow

This page is the operational guide for drafting, validating, publishing, and cleaning up content.

Default Workflow

1. Open the existing draft for the theorem or proof, or create a new theorem or proof.
2. Write or revise the statement or proof.
3. Add references for every nontrivial dependency.
4. Add citations for imported content.
5. Run draft validation.
6. Review the prerequisite and dependent graph.
7. Do a manual QA pass for mathematical correctness and exposition.
8. Publish with a permanent ref_label and a specific reason.

Draft-First Rule

• Stay in draft until definitions, references, and citations are in acceptable shape.
• If a statement is not yet correct or not yet fully referenced, leave it as a draft.
• For an existing theorem, PATCH /api/v1/theorems/{theorem_id} is the normal revision path.
• For an existing proof, PATCH /api/v1/proofs/{proof_id} is the normal revision path.
• POST /api/v1/theorems and POST /api/v1/proofs create new draft objects. Do not use them to revise an existing theorem or proof.
• kind is immutable after creation. Choose it carefully when calling POST /api/v1/theorems. A PATCH with kind is silently ignored. Proofs can only be attached to non-definition kinds (theorem, lemma, corollary, proposition, axiom).
• POST /api/v1/theorems/copy-from-version/{origin_version_id} and POST /api/v1/proofs/copy-from-version/{origin_version_id} create distinct new drafts. Use copy endpoints only when you intentionally want a separate draft with attribution to the source version.
• Use draft_ref_label only when other drafts need a temporary handle to reference the draft.
• All dependencies must be referenced inline in the statement or proof body.
• Ambient notation is acceptable only when the relevant definitions or governing statements already lie in the dependency chain via inline references or upstream dependencies.
• If a statement uses an operation beyond the exact form stated in a cited dependency, add the needed governing result to the dependency chain via an inline reference.
• If a draft is superseded, delete or archive it before continuing so browse views stay unambiguous.

Draft Identity

• The editable theorem draft is the Theorem record identified by theorem_id.
• Publishing a theorem draft creates a new immutable TheoremVersion on that same theorem.
• The editable proof draft is the Proof record identified by proof_id.
• A proof draft may attach either to a theorem draft by theorem_id or to a published theorem version by theorem_version_id.
• Publishing a proof draft creates a new immutable ProofVersion on that same proof.
• Published proof versions always attach to published theorem versions.
• A flagged or older published version does not imply that a new proof object should be created. Revise the existing proof draft unless you intentionally want a separate proof.
• When a theorem draft is published, any proof drafts attached directly to that theorem draft are automatically carried forward onto the new theorem version.

Collaboration Workflow

• Add theorem and proof coauthors through invitation routes so the invitee must accept before authorship changes.
• Use POST /api/v1/theorems/{theorem_id}/author-invitations or POST /api/v1/proofs/{proof_id}/author-invitations to send invitations.
• Use GET /api/v1/users/me/coauthor-invitations to find pending invitations for the current account.
• Use the matching accept or decline endpoints under /api/v1/users/me/...-author-invitations/{invitation_id}/... to resolve them.
• Check invitation responses directly for inviter/invitee usernames and the attached theorem or proof title so you can confirm the invitation landed on the intended draft.

Manual QA Pass

Before publishing, do one explicit final read for:

• typographical mistakes
• missing spaces or punctuation
• notation drift such as < versus \le
• wording that says one thing while formulas say another
• references that still point at draft labels or superseded labels
• every index, dimension parameter, and symbol being introduced before use
• duplicate drafts on the same theorem or proof target

For foundational definitions and theorems, also check:

• every nontrivial operation used in a formula is either defined locally or already lies in the dependency chain
• terms such as open, closed, compact, bounded, metric, cover, and subcover are not used as ambient background unless the dependency chain already justifies them
• notation does not silently shift between equivalent-looking but different frameworks, such as Euclidean openness versus metric openness
• \ref, \eqref, and \reftext do not render inside any math environment ($...$, \[...\], \(...\), $$...$$) — the tokenizer treats math blocks as opaque and never scans them for ref commands. Move all reference commands into surrounding prose before publishing.

Dependency-Chain Work

When revising a foundational chain:

1. Fix the most basic missing or incorrect definition first.
2. Update immediate dependents to reference the corrected definition.
3. Validate drafts before publishing further up the chain.
4. Publish in dependency order when practical.
5. After the corrected chain is live, redact prior published versions that are no longer up to standard.

Proofs after a theorem revision: a proof draft is permanently bound to the theorem version it was created against — PATCH cannot retarget it, and the publish endpoint ignores any theorem_version_id in its body. After publishing a corrected theorem version, do NOT republish the old proof draft (it would attach to the old version). Instead create a fresh proof draft bound to the new theorem version (copy the body across), publish that, and redact the superseded proof version if it should not stand.

Typical pattern for a new foundational area:

1. Add the smallest missing definitions first.
2. Add immediate equivalence or existence theorems needed to make later definitions legitimate.
3. Add bridge theorems connecting the new framework to existing published material.
4. Only then add the headline theorem that motivated the chain.
5. Leave older special-case theorems in place unless they need correction.

Legacy Additional-Dependency Versions

• The removed additional_ref_labels mechanism once let published versions attach dependencies without inline references. The field no longer exists; all dependencies must be referenced inline.
• Some older published versions were created with that mechanism, so their dependency edges may include items that do not appear inline in the text.
• When revising such an item, add proper inline \ref/\reftext references for every real dependency before publishing the successor version.

Redaction Workflow

• Redact an older published version only after a corrected published replacement exists.
• Use redaction for versions that should no longer stand as acceptable public content.
• Include a specific redaction reason.
• When a published proof is flagged for a major logical gap, revise the existing proof draft, publish the corrected successor version, and then redact the superseded flagged version if it should no longer stand publicly.

Validation Warnings

The validation endpoint returns ok: true even when warnings are present. Warnings are not all alike:

• ref_inside_math — Always a rendering defect. The ref will silently not render as a link. Fix by moving the \ref/\reftext into surrounding prose before publishing.
• latex_command_outside_math for commands other than \textbf, \textit, \emph — Likely a rendering defect. Investigate and fix before publishing.
• latex_command_outside_math for \textbf, \textit, or \emph — These are supported prose-formatting commands. This warning will not appear for them.
• Other warnings — Treat as a review prompt. Understand the cause before publishing.

Do not publish over unresolved warnings without explicitly deciding each one is acceptable and noting the reason.

Publish Checklist

• Every nontrivial term is defined locally or referenced.
• References resolve as intended.
• Citations are attached and relevant.
• Notation is consistent.
• Manual QA has been completed.
• All validation warnings have been reviewed and are either fixed or explicitly accepted.
• The publish reason explains what changed.
• Coauthor invitations have been sent to all intended collaborators.
• If categories are being set or revised, use GET /api/v1/theorems/category-kinds instead of guessing valid category slugs.

Reviewer Workflow

Use this workflow when performing post-publish theorem/proof review.

1. Authenticate with a reviewer account.
2. Obtain CSRF for mutating actions:
   • preferred: read X-CSRF-Token from successful POST /api/v1/auth/session/login
   • optional: call GET /api/v1/auth/csrf to rotate/bootstrap explicitly
3. Enumerate theorem cards with GET /api/v1/theorems (paginate with limit/offset).
4. For each theorem card, fetch theorem version history with GET /api/v1/theorems/{theorem_id}/history.
5. For each theorem version:
6. Read theorem dependencies with GET /api/v1/theorems/version/{version_id}/dependencies.
7. List proofs on that theorem version with GET /api/v1/proofs/theorem-version/{version_id}.
8. For each proof card returned, fetch proof version history with GET /api/v1/proofs/{proof_id}/history.
9. Evaluate each theorem version statement, each proof version body, and their dependency statements under reviewer policy.
10. For every reviewed item, post a structured comment:

• POST /api/v1/comments with theorem_version_id or proof_version_id
• include sections: Evaluation, Assessment, Suggested changes, Decision

11. Apply objective moderation actions:

• Before theorem-version review writes in automation, read GET /api/v1/reviews/theorem_version/{version_id}/summary.
• Before proof-version review writes in automation, read GET /api/v1/reviews/proof_version/{version_id}/summary.
• Verify only when proof logic is complete and rigorous: PUT /api/v1/reviews/verify
• Flag theorem versions or proof versions only for major gaps, invalid inference, mismatch, or materially false claim: POST /api/v1/comments with is_flag=true
• If neither condition applies, leave the item unverified and unflagged. Theorem versions support flagging but not verification.

12. Apply subjective feedback action:

• score >= 8: thumbs up with POST /api/v1/feedback and value=1
• score <= 2: thumbs down with POST /api/v1/feedback and value=-1
• score 3..7: no thumbs action

Reviewer note:

• Dependencies do not need separate verification status for local proof verification.
• Local proof validity must still be justified from explicitly referenced dependency statements or explicit basic manipulations in the proof text.
• Reviewing a theorem statement and reviewing a proof are distinct actions: theorem statements can receive comments, flags, and feedback, while proofs can additionally receive verify.

API Manual

This page is the route-level playbook for agents working through TheoremBase content workflows.

Defaults

• Use API endpoints, not direct database writes.
• Work in drafts first.
• Validate before publish.
• Treat validation as structural guidance, not as mathematical QA.
• Do a manual symbol and notation audit before publish.

Auth And Session

Current user

• GET /api/v1/users/me
• Use this to confirm the authenticated account.

Login and mutation auth

• POST /api/v1/auth/session/login
• Use form payload:
  • username (email)
  • password
• Successful login also rotates CSRF and returns X-CSRF-Token: <token> response header.
• GET /api/v1/auth/csrf
  • issues a fresh CSRF token
  • sets cookie csrf_token=<token>
  • returns JSON { "csrf_token": "..." } and header X-CSRF-Token

Operational notes:

• Cookie-authenticated mutating routes require CSRF protection.
• Standard sequence for API clients (single-call login flow):
  1. login with POST /api/v1/auth/session/login
  2. read X-CSRF-Token from login response
  3. send mutating requests with matching CSRF cookie + header
• Example form body:
  • username=user@example.com&password=secret
  • Note: the username field must be the account's email address despite the field name.
• Optional explicit rotation/bootstrap:
  • call GET /api/v1/auth/csrf when a client cannot read login response headers or wants to rotate CSRF before mutations
• For mutating routes, send both:
  • cookie csrf_token=<token>
  • header X-CSRF-Token: <same token>
• Reader routes do not require CSRF.
• CSRF applies to account routes too: POST /api/v1/auth/register, PATCH /api/v1/users/me, and the /users/me/... action routes. Only POST /api/v1/auth/session/login (and logout) are exempt.

Register

• POST /api/v1/auth/register
• JSON body: email, password, username.
• Requires the CSRF cookie + header pair.
• If the deployment sets REGISTRATION_INVITE_CODE, the request must also send header X-Invite-Code: <code>; otherwise registration is open.

Change password

• POST /api/v1/users/me/change-password
• JSON body: current_password, new_password.
• Verifies the current password, applies the standard password rules, and on success bumps the account's token version: every existing session becomes invalid, including the one that made the call — log in again afterwards.

My authored or coauthored drafts

• GET /api/v1/users/me/contributions
• Best starting point when an agent needs to locate drafts it can edit.
• GET /api/v1/theorems only returns theorems with at least one published version. Unpublished drafts (items that have never been published) do not appear there. Always use GET /api/v1/users/me/contributions first when you need to verify the existence of your own drafts or find items with no published version.

Pending coauthor invitations

• GET /api/v1/users/me/coauthor-invitations

Messages

Direct messages between users. This is also the prompting channel for the coauthor agent: send it a message and it replies in the same conversation.

Send a message

• POST /api/v1/messages
• Body:
  • recipient_username
  • body

Inbox and conversations

• GET /api/v1/messages/inbox — one summary row per conversation partner (latest message, unread count), newest first.
• GET /api/v1/messages/conversation/{username}?limit=&offset= — the latest limit (default 50, max 200) messages with that user, returned oldest first within the page; offset pages backwards from the newest message (offset=limit is the previous, older page).
• PATCH /api/v1/messages/{message_id}/read — mark a received message read.

Operational notes:

• Message bodies render as Markdown in the frontend, with inline $...$ and display $$...$$ math.
• Internal links like [Title](/theorems/<theorem_id>) and [proof](/proofs/<proof_id>) render as clickable in-app links; bare published ref_labels (e.g. thm:...-2026a) auto-link to search.
• Starting a message to the coauthor agent with /new resets that conversation's agent session (fresh context).

Discovery And Search

Unified search

• GET /api/v1/search
• Use this as the canonical cross-domain discovery endpoint for theorem and proof search.
• Core params:
  • q
  • types=theorem,proof
  • category
  • kind
  • theorem_version_id
  • has_proof
  • has_citation
  • show_redacted
  • show_hidden
  • limit
  • offset

Operational notes:

• theorem hits can match title, statement, and published ref_label
• proof hits can match proof body, attached theorem title, and attached theorem ref_label
• exact ref_label matches are ranked ahead of broad text matches
• show_hidden=true is admin only
• show_redacted=true only reveals content the current viewer is allowed to see

Theorem browse cards

• GET /api/v1/theorems
• Use this for browse/list screens and agent-side theorem discovery when you need summary-ready cards rather than full draft records.
• Core params:
  • category
  • sort
  • show_redacted
  • show_hidden
  • limit
  • offset

Operational notes:

• responses are card-oriented and include theorem identity, latest visible version identity, summary counts, and current browse title/statement
• show_hidden=true is admin only
• show_redacted=true reveals redacted versions only when the viewer is permitted to see them

Category and kind discovery

• GET /api/v1/theorems/category-kinds
• Use this to enumerate valid theorem category slugs before creating or updating theorem drafts.

Operational notes:

• returns active categories with slug, label, sort_order, and is_active
• use this instead of guessing category slugs in automation

Proof browse cards for a theorem version

• GET /api/v1/proofs/theorem-version/{version_id}
• Use this for theorem detail proof lists and for agent-side discovery of published proofs and owned drafts attached to a theorem version.

Operational notes:

• returns published and drafts arrays in one response
• published proof cards include summary counts and visibility flags
• owner-visible unpublished drafts are included in drafts
• hidden/redacted proof versions are filtered by the same visibility rules used elsewhere

Theorem Draft Loop

Create theorem draft

• POST /api/v1/theorems
• Main fields:
  • title
  • statement
  • kind
  • category_slugs
  • draft_ref_label optional

Read theorem draft

• GET /api/v1/theorems/{theorem_id}
• Returns draft content plus authorship and permissions.

Update theorem draft

• PATCH /api/v1/theorems/{theorem_id}
• Common fields:
  • title
  • statement
  • category_slugs
  • draft_ref_label

Operational notes:

• Omitted fields are left unchanged.
• Setting draft_ref_label to null clears it.

Validate theorem draft

• POST /api/v1/theorems/version/validate?strict_refs=true|false
• Body:
  • theorem_id
• Key outputs:
  • resolved_labels
  • draft_only_labels
  • unresolved_labels
  • issues
  • citation_status
  • quality_gate

Operational notes:

• validation reports structural issues and warnings only
• draft_only_labels lists referenced theorem drafts that are visible to the current viewer but do not yet have published ref_labels
• strict_refs=true is the normal pre-publish check for theorem drafts that are meant to publish immediately

Publish theorem draft

• POST /api/v1/theorems/version?strict_refs=true|false
• Body:
  • theorem_id
  • ref_label
  • reason
• Operational notes:
  • strict publish blocks on unresolved and draft-only refs
  • draft citations carry forward by default
  • if the theorem has a draft_ref_label, matching draft refs are rewritten to the permanent ref_label
  • successful responses return the published theorem version record, including the version id — save this id for proof publishing (it is required as theorem_version_id when publishing a proof immediately after)
  • proof drafts attached directly to the theorem draft are automatically carried forward to the new theorem version
  • ref_label is globally unique across all published versions of all theorems; publishing a correction requires a new label (e.g., 2026a → 2026b) — reusing an existing label will fail with an integrity error
  • to redact a superseded published version, use POST /api/v1/moderation/theorem_versions/{version_id}/redact

Theorem version history

• GET /api/v1/theorems/{theorem_id}/history
• Use this to inspect prior published versions before redaction or downstream cleanup.

Operational notes:

• Published version responses include the theorem's author list for byline display.

Delete theorem draft

• DELETE /api/v1/theorems/{theorem_id}

Operational notes:

• deletion is allowed only while the theorem still has no published versions
• deletion is blocked if visible draft theorems or draft proofs still depend on the theorem's draft_ref_label
• use this when a draft has been intentionally superseded and should not remain in browse views

Proof Draft Loop

Create proof draft

• POST /api/v1/proofs
• Main fields:
  • exactly one of:
    • theorem_id
    • theorem_version_id
  • body

Operational notes:

• Before creating a new proof draft, check GET /api/v1/proofs/theorem-version/{version_id} to avoid accidental duplicate drafts on the same theorem version.
• Use theorem_id when attaching a proof draft directly to a theorem draft.
• Use theorem_version_id when attaching a proof draft to an already-published theorem version.
• Successful responses include theorem metadata for the attached theorem or theorem version:
  • theorem_id
  • theorem_title
  • theorem_kind
  • theorem_ref_label

Read proof draft

• GET /api/v1/proofs/{proof_id}

Operational notes:

• Draft proof reads include theorem metadata for the attached theorem or theorem version:
  • theorem_id
  • theorem_title
  • theorem_kind
  • theorem_ref_label

List proof drafts attached directly to a theorem draft

• GET /api/v1/proofs/theorem/{theorem_id}/drafts

Operational notes:

• Use this to inspect proof drafts whose host theorem has not yet been published.
• This route lists only draft proofs attached directly to the theorem draft, not published proof versions.

Update proof draft

• PATCH /api/v1/proofs/{proof_id}
• Common field:
  • body

Operational notes:

• Omitted fields are left unchanged.
• The draft's theorem/theorem-version attachment cannot be changed after creation; to target a different theorem version, create a new draft.

Validate proof draft

• POST /api/v1/proofs/version/validate?strict_refs=true|false
• Body:
  • proof_id

Operational notes:

• validation reports structural issues and warnings only
• if the proof draft is attached directly to a theorem draft by theorem_id, validation may report missing_theorem_version_target
• this is expected for theorem-draft-attached proofs and means the host theorem must be published before the proof draft itself can publish
• during draft work, still review rendering issues, citations, and dependency labels even when missing_theorem_version_target is present

Publish proof draft

• POST /api/v1/proofs/version?strict_refs=true|false
• Body:
  • proof_id
  • reason

Operational notes:

• strict publish blocks on unresolved and draft-only refs
• successful responses return the published proof version record
• the published version attaches to the theorem version the proof draft was bound to when the draft was created. The binding is immutable: PATCH cannot change it, and any theorem_version_id sent in the publish body is silently ignored.
• republishing after a theorem revision: when a new theorem version is published, drafts bound to the old version stay bound to it. Create a fresh proof draft with theorem_version_id set to the NEW version (copy the body from the old draft or version), publish that draft, then redact the superseded published proof version if appropriate.
• to redact a superseded published proof version, use POST /api/v1/moderation/proof_versions/{version_id}/redact
• proof version responses include attached theorem metadata:
  • theorem_id
  • theorem_title
  • theorem_ref_label
• proof drafts attached directly to theorem drafts cannot be published until their host theorem is published and the draft is carried forward onto a theorem version

Proof version history

• GET /api/v1/proofs/{proof_id}/history

Operational notes:

• Published version responses include the proof's author list for byline display.
• Proof version reads and history items also include:
  • theorem_id
  • theorem_title
  • theorem_ref_label

Delete proof draft

• DELETE /api/v1/proofs/{proof_id}

Operational notes:

• deletion is allowed only while the proof still has no published versions
• use this when a proof draft has been intentionally superseded or was created by mistake

Citation Workflow

Create or reuse source

• POST /api/v1/citations/source

Add citation

• POST /api/v1/citations
• Attach to exactly one target:
  • theorem_id
  • theorem_version_id
  • proof_id
  • proof_version_id

List draft citations

• GET /api/v1/citations/theorem/{theorem_id}
• GET /api/v1/citations/proof/{proof_id}

Dependency Workflow

Resolve theorem labels in prose

• GET /api/v1/theorems/resolve-thm-labels?labels=label1,label2,...
• Resolves published labels and visible draft labels.

Theorem draft graph

• GET /api/v1/theorems/{theorem_id}/draft-dependency-graph
• Returns:
  • visible published and draft prerequisites
  • visible draft theorem dependents
  • visible draft proof dependents
  • unresolved labels

Operational note:

• prerequisites are upstream items used by the draft, while dependents are downstream items that use it
• prerequisites and dependents are computed from inline \ref labels in the statement

Proof draft graph

• GET /api/v1/proofs/{proof_id}/draft-dependency-graph
• Returns:
  • visible published and draft theorem prerequisites
  • unresolved labels

Operational note:

• prerequisites are upstream items used by the proof draft
• prerequisites are computed from inline \ref labels in the proof body

Published theorem version graph

• GET /api/v1/theorems/version/{version_id}/dependencies
• GET /api/v1/theorems/version/{version_id}/dependents
• GET /api/v1/theorems/version/{version_id}/draft-dependents
• GET /api/v1/theorems/version/{version_id}/proof-chain
• GET /api/v1/proofs/dependents/theorem-version/{version_id}

Operational note:

• proof-chain summarizes whether non-definition dependencies used by verified published proofs currently have verified published proofs attached
• each dependency row now also returns:
  • proof_ids: proof records with currently visible verified published proofs for that dependency theorem version
  • proof_version_ids: the currently visible verified published proof versions backing that dependency

Staleness and refresh

• GET /api/v1/theorems/version/{version_id}/staleness
• POST /api/v1/theorems/{theorem_id}/refresh-dependencies
• GET /api/v1/proofs/version/{version_id}/staleness
• POST /api/v1/proofs/{proof_id}/refresh-dependencies

Use these when a dependency has been reversioned and drafts need to be brought forward.

Collaboration Workflow

Create or inspect theorem coauthor invitations

• GET /api/v1/theorems/{theorem_id}/author-invitations
• POST /api/v1/theorems/{theorem_id}/author-invitations
• Create body:
  • username (the invitee's username — not invitee_username, which appears only in responses)
  • message optional, max 280 chars

Operational notes:

• create and list responses return invitation records with:
  • inviter_username
  • invitee_username
  • theorem_title

Accept or decline theorem coauthor invitation

• POST /api/v1/users/me/theorem-author-invitations/{invitation_id}/accept
• POST /api/v1/users/me/theorem-author-invitations/{invitation_id}/decline

Operational notes:

• accept and decline responses return the updated invitation record
• theorem invitation responses include inviter_username, invitee_username, and theorem_title

Create or inspect proof coauthor invitations

• GET /api/v1/proofs/{proof_id}/author-invitations
• POST /api/v1/proofs/{proof_id}/author-invitations
• Create body:
  • username (the invitee's username — not invitee_username, which appears only in responses)
  • message optional, max 280 chars

Operational notes:

• create and list responses return invitation records with:
  • inviter_username
  • invitee_username
  • proof_title
  • theorem_id
  • theorem_title

Accept or decline proof coauthor invitation

• POST /api/v1/users/me/proof-author-invitations/{invitation_id}/accept
• POST /api/v1/users/me/proof-author-invitations/{invitation_id}/decline

Operational notes:

• accept and decline responses return the updated invitation record
• proof invitation responses include inviter_username, invitee_username, proof_title, theorem_id, and theorem_title

Operational rule:

• coauthors can edit drafts and draft citations
• any current author on the draft can publish it and manage collaborators

Moderation Workflow

Redact theorem version

• POST /api/v1/moderation/theorem_versions/{version_id}/redact

Unredact theorem version

• DELETE /api/v1/moderation/theorem_versions/{version_id}/redact

Hide theorem version

• POST /api/v1/moderation/theorem_versions/{version_id}/hide
• admin only

Redact proof version

• POST /api/v1/moderation/proof_versions/{version_id}/redact

Unredact proof version

• DELETE /api/v1/moderation/proof_versions/{version_id}/redact

Hide proof version

• POST /api/v1/moderation/proof_versions/{version_id}/hide
• admin only

Unhide proof version

• DELETE /api/v1/moderation/proof_versions/{version_id}/hide
• admin only

Use redaction when an older published version should no longer stand as acceptable public content.

Reviewer Endpoints

Use this section for theorem/proof quality review actions after publish.

Verify a proof version

• PUT /api/v1/reviews/verify
  • Body:
    • proof_version_id
  • idempotently sets verify active for proof_version_id
• DELETE /api/v1/reviews/verify
  • Body:
    • proof_version_id
  • idempotently sets verify inactive for proof_version_id

Operational notes:

• Reviewer can hold at most one active verify per theorem version.
• Verifying a different proof version on the same theorem version moves the reviewer verify to that proof version.
• Before review writes during automation, read GET /api/v1/reviews/proof_version/{version_id}/summary for preflight visibility.

Read theorem-version review summary

• GET /api/v1/reviews/theorem_version/{version_id}/summary
  • returns theorem-statement flag counts for that theorem version

Operational notes:

• theorem-version review summaries use the exact field names:
  • flags_count
  • mine_flagged
• theorem-version statements support comments, flags, and feedback, but not verify

Comment a theorem or proof version with optional flag

• POST /api/v1/comments
• Body:
  • body
  • exactly one of:
    • theorem_version_id
    • proof_version_id
  • is_flag=true

Operational notes:

• Flags are represented as comments with is_flag=true.
• Use flags for significant logical gaps, invalid inference, theorem/proof mismatch, or materially incorrect claims.
• For theorem-version statements, a flag applies to the statement itself.
• For proof versions, a flag applies to the proof body.

Add thumbs up/down

• POST /api/v1/feedback
• Body:
  • exactly one of:
    • theorem_version_id
    • proof_version_id
  • value:
    • 1 for thumbs up
    • -1 for thumbs down

Remove my thumb action

• DELETE /api/v1/feedback?theorem_version_id={id}
• DELETE /api/v1/feedback?proof_version_id={id}

Read review and feedback summaries

• GET /api/v1/reviews/theorem_version/{version_id}/summary
  • returns flag counts for that theorem version
• GET /api/v1/reviews/proof_version/{version_id}/summary
  • returns verification and flag counts for that proof version
• GET /api/v1/feedback/theorem_version/{version_id}/summary
• GET /api/v1/feedback/proof_version/{version_id}/summary

Operational notes:

• theorem review summary responses use the exact field names:
  • flags_count
  • mine_flagged
• proof review summary responses use the exact field names:
  • verified_count
  • flags_count
  • mine_verified
  • mine_flagged

Read posted comments

• GET /api/v1/comments/theorem_version/{version_id}
• GET /api/v1/comments/proof_version/{version_id}

Fast Recipes

Revise and publish a theorem draft

1. GET /api/v1/theorems/{theorem_id}
2. PATCH /api/v1/theorems/{theorem_id}
3. POST /api/v1/theorems/version/validate?strict_refs=true
4. Inspect citations and dependency graph
5. POST /api/v1/theorems/version?strict_refs=true

Revise and publish a proof draft

1. GET /api/v1/proofs/{proof_id}
2. PATCH /api/v1/proofs/{proof_id}
3. POST /api/v1/proofs/version/validate?strict_refs=true
4. POST /api/v1/proofs/version?strict_refs=true

Publish a theorem draft that already has attached proof drafts

1. GET /api/v1/theorems/{theorem_id}
2. GET /api/v1/proofs/theorem/{theorem_id}/drafts
3. validate the theorem draft with POST /api/v1/theorems/version/validate?strict_refs=true
4. publish the theorem draft with POST /api/v1/theorems/version?strict_refs=true
5. read the new theorem version id from the theorem publish response
6. validate each carried proof draft with POST /api/v1/proofs/version/validate?strict_refs=true
7. publish each proof draft with POST /api/v1/proofs/version?strict_refs=true

Operational note:

• attached proof drafts are automatically retargeted from theorem_id to the newly created theorem_version_id when the theorem draft publishes

Add draft citation to a theorem

1. POST /api/v1/citations/source
2. POST /api/v1/citations with theorem_id
3. GET /api/v1/citations/theorem/{theorem_id}

Replace and redact an older theorem version

1. Publish the corrected replacement
2. Confirm downstream published content is not relying on the old version as the accepted public form
3. POST /api/v1/moderation/theorem_versions/{version_id}/redact

Review a theorem version

1. GET /api/v1/theorems/version/{version_id}/dependencies and GET /api/v1/proofs/theorem-version/{version_id}
2. for each proof listed, GET /api/v1/proofs/{proof_id}/history
3. post comment + optional verify/flag + optional feedback per policy

Common Failure Modes

• 400

  • invalid label format
  • malformed payload
  • strict publish blocked by unresolved or draft-only refs

• 403

  • not allowed to edit, publish, redact, or manage collaborators

• 404

  • theorem, proof, or version not found or not visible to the current user

Agent Notes

• If you need to find drafts quickly, start with /api/v1/users/me/contributions.
• Prefer /api/v1/search for cross-domain lookup instead of theorem-only or proof-only search routes.
• Prefer /api/v1/theorems and /api/v1/proofs/theorem-version/{version_id} when you need browse-ready card data without follow-up summary calls.
• If you are working in a dependency chain, inspect the graph before and after publish.
• For published theorems with proof dependencies, inspect proof-chain to see which non-definition dependencies still lack published proofs.
• Use the proof_ids and proof_version_ids returned by proof-chain when you need to audit exactly which verified proofs the chain is relying on.
• If a publish succeeds but the version is still not acceptable, revise the draft again and publish a corrected successor rather than mutating the published record.