openapi.yaml

openapi: 3.1.0
info:
  title: Vdoc API
  version: 0.1.0
  description: Machine-readable contract for the Vdoc v0.1 HTTP API. Projects own typed Documents, including OpenAPI and Markdown. REST handlers return HTTP 200 with the semantic result in the Vdoc envelope body.
servers:
  - url: /
security: []
tags:
  - name: Open
    description: Public health, authentication, docs, and MCP entry points.
  - name: Document Shares
    description: Admin-managed document share links and minimal anonymous published-content access.
  - name: Identity
    description: Current user identity.
  - name: System Users
    description: Super admin user lifecycle and user MCP token oversight.
  - name: Teams
    description: Team lifecycle.
  - name: Projects
    description: Project lifecycle and membership.
  - name: Documents
    description: Project document lifecycle.
  - name: Branches
    description: Document branch lifecycle.
  - name: Drafts
    description: Document draft creation, update, review, and promotion.
  - name: Versions
    description: Published document versions and stored content.
  - name: Endpoints
    description: Parsed endpoint data from published document versions.
  - name: Diffs
    description: Document version comparison.
  - name: Audit Logs
    description: Filtered audit history for super administrators and project administrators.
  - name: MCP Tokens
    description: User MCP token lifecycle.
  - name: AI
    description: Built-in Admin AI provider, prompt, summary, and page chat APIs. AI can summarize and explain only; it cannot approve, request changes, reject, publish, or modify drafts or versions. Draft submit and version publish attempt summaries after the state change is saved. Skipped or failed summaries are stored without blocking submit or publish. AI audit metadata may include prompt_tokens, completion_tokens, and total_tokens, but never raw API keys, JWTs, MCP tokens, or Authorization headers.
paths:
  /api/v1/open/health:
    get:
      tags: [Open]
      summary: Get health.
      operationId: getOpenHealth
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/auth/register:
    post:
      tags: [Open]
      summary: Register a user and issue a JWT when anonymous registration is enabled.
      description: Disabled by default. Operators must explicitly set auth.allow_registration=true only for trusted disposable or pilot environments.
      operationId: registerAuth
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AuthRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/auth/login:
    post:
      tags: [Open]
      summary: Authenticate a user and issue a JWT.
      operationId: loginAuth
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AuthRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/auth/config:
    get:
      tags: [Open]
      summary: Read public authentication capabilities.
      description: Returns whether anonymous registration is enabled so clients can hide unavailable registration flows.
      operationId: getAuthConfig
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/docs/openapi.yaml:
    get:
      tags: [Open]
      summary: Serve this OpenAPI YAML document.
      operationId: getOpenAPISpec
      responses:
        "200": { $ref: "#/components/responses/OpenAPISpecResponse" }
  /api/v1/open/mcp:
    post:
      tags: [Open]
      summary: Call MCP tools through JSON-RPC 2.0.
      description: Every authenticated `tools/list` and `tools/call` request records a sanitized `mcp.tool_call` audit event. Successful published-content tools are marked with `evidence_kind=published_content_read` and retain only the tool, adapter, result/reason, MCP token ID, and referenced project/document/branch/draft/version/endpoint/diff IDs. Raw MCP token secrets, request arguments, OpenAPI schemas, and Markdown content are never copied into audit metadata.
      operationId: callMCP
      security:
        - MCPTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MCPCallRequest" }
      responses:
        "200": { $ref: "#/components/responses/MCPJSONRPCResponse" }
  /api/v1/open/document-shares/{share_id}:
    parameters:
      - { $ref: "#/components/parameters/ShareID" }
    get:
      tags: [Document Shares]
      summary: Read minimal metadata for an authorized public document share.
      operationId: getPublicDocumentShare
      security: [{ DocumentShareAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/document-shares/{share_id}/unlock:
    parameters:
      - { $ref: "#/components/parameters/ShareID" }
    post:
      tags: [Document Shares]
      summary: Exchange a valid share password for a short-lived memory-only unlock proof.
      operationId: unlockPublicDocumentShare
      security: [{ DocumentShareAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DocumentShareUnlockRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/document-shares/{share_id}/versions:
    parameters:
      - { $ref: "#/components/parameters/ShareID" }
    get:
      tags: [Document Shares]
      summary: List published versions allowed by an all-versions share.
      operationId: listPublicDocumentShareVersions
      security: [{ DocumentShareAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/open/document-shares/{share_id}/versions/{version_id}/content:
    parameters:
      - { $ref: "#/components/parameters/ShareID" }
      - { $ref: "#/components/parameters/VersionID" }
    get:
      tags: [Document Shares]
      summary: Read an allowed immutable published snapshot.
      operationId: getPublicDocumentShareContent
      security: [{ DocumentShareAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/open/document-shares/{share_id}/versions/{version_id}/download:
    parameters:
      - { $ref: "#/components/parameters/ShareID" }
      - { $ref: "#/components/parameters/VersionID" }
    get:
      tags: [Document Shares]
      summary: Download an allowed immutable published source file through Vdoc authorization.
      operationId: downloadPublicDocumentShareVersion
      security: [{ DocumentShareAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/PublicDocumentDownloadResponse" }
  /api/v1/private/identity/me:
    get:
      tags: [Identity]
      summary: Get current user.
      description: Returns the active identity plus can_access_audit, a server-computed capability used by clients without enumerating project memberships.
      operationId: getIdentityMe
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/system/users:
    get:
      tags: [System Users]
      summary: List users.
      operationId: listSystemUsers
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [System Users]
      summary: Create user.
      operationId: createSystemUser
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateUserRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/system/users/{user_id}:
    parameters:
      - { $ref: "#/components/parameters/UserID" }
    patch:
      tags: [System Users]
      summary: Patch user.
      operationId: patchSystemUser
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchUserRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/system/users/{user_id}/mcp-tokens:
    parameters:
      - { $ref: "#/components/parameters/UserID" }
    get:
      tags: [System Users]
      summary: List a user's MCP tokens.
      operationId: listSystemUserMCPTokens
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/system/users/{user_id}/mcp-tokens/{token_id}/revoke:
    parameters:
      - { $ref: "#/components/parameters/UserID" }
      - { $ref: "#/components/parameters/TokenID" }
    post:
      tags: [System Users]
      summary: Revoke a user's MCP token.
      operationId: revokeSystemUserMCPToken
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/teams:
    get:
      tags: [Teams]
      summary: List teams (SuperAdmin only).
      operationId: listTeams
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Teams]
      summary: Create team.
      operationId: createTeam
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NameDescriptionRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/teams/{team_id}:
    parameters:
      - { $ref: "#/components/parameters/TeamID" }
    get:
      tags: [Teams]
      summary: Get team (SuperAdmin only).
      operationId: getTeam
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    patch:
      tags: [Teams]
      summary: Update team.
      operationId: updateTeam
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchNameDescriptionRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/teams/{team_id}/archive:
    parameters:
      - { $ref: "#/components/parameters/TeamID" }
    post:
      tags: [Teams]
      summary: Archive team.
      operationId: archiveTeam
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects:
    get:
      tags: [Projects]
      summary: List projects.
      operationId: listProjects
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Projects]
      summary: Create project.
      operationId: createProject
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateProjectRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [Projects]
      summary: Get project.
      operationId: getProject
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    patch:
      tags: [Projects]
      summary: Update project.
      operationId: updateProject
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchNameDescriptionRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/archive:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    post:
      tags: [Projects]
      summary: Archive project.
      operationId: archiveProject
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/members:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [Projects]
      summary: List project members.
      operationId: listProjectMembers
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Projects]
      summary: Add project member.
      operationId: addProjectMember
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AddProjectMemberRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/member-candidates:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [Projects]
      summary: List active users eligible to join the project.
      description: Project Admin or SuperAdmin only. Existing active project members and disabled users are excluded.
      operationId: listProjectMemberCandidates
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/members/{user_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/UserID" }
    delete:
      tags: [Projects]
      summary: Remove project member.
      operationId: removeProjectMember
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/members/{user_id}/role:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/UserID" }
    patch:
      tags: [Projects]
      summary: Change project member role.
      operationId: patchProjectMemberRole
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              { $ref: "#/components/schemas/PatchProjectMemberRoleRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [Documents]
      summary: List project documents.
      operationId: listProjectDocuments
      security: [{ JWTAuth: [] }]
      parameters:
        - name: document_type
          in: query
          required: false
          schema: { type: integer, minimum: 1 }
          description: Filter documents by type code (1 OpenAPI, 2 Markdown).
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Documents]
      summary: Create project document.
      description: Creates a typed Document. document_type 1 is OpenAPI and 2 is Markdown. relative_path is the stored project-local path identity.
      operationId: createProjectDocument
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DocumentRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Documents]
      summary: Get project document.
      operationId: getProjectDocument
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    patch:
      tags: [Documents]
      summary: Update project document.
      description: Updates document metadata only. Lifecycle status cannot be changed here; use the archive action. Invalid lifecycle input is rejected before any metadata is committed.
      operationId: updateProjectDocument
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchDocumentRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/overview:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Documents]
      summary: Read document statistics without downloading bodies or full lists.
      description: "Detail contains version_count, endpoint_count, latest_version (public version DTO or null), published_branch_ids (active published branches), has_reviewed_draft (submitted or published draft on an active branch), raw_size_bytes and nullable raw_line_count. Requires document read permission."
      operationId: getDocumentOverview
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/mcp-readiness:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Documents]
      summary: Read the latest successful Agent document read across all history.
      description: "Detail contains nullable last_read_at. Only the current user's active unexpired tokens with the document's matching read scope count. Requires document read permission; archived parents return null."
      operationId: getDocumentMCPReadiness
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/archive:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    post:
      tags: [Documents]
      summary: Archive project document.
      operationId: archiveProjectDocument
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/shares:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Document Shares]
      summary: List retained public-share history for a document.
      operationId: listDocumentShares
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Document Shares]
      summary: Create an immutable branch-bound public-share policy and return its capability once.
      description: Requires an active Project, Document, and Branch with at least one published version. Archived parents retain list and revoke access but block creation.
      operationId: createDocumentShare
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateDocumentShareRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/shares/{share_id}/reveal:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/ShareID" }
    post:
      tags: [Document Shares]
      summary: Reveal an active share capability without returning its password.
      description: Requires active parent resources. Archived parents retain list and revoke access but block capability reveal.
      operationId: revealDocumentShare
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/shares/{share_id}/revoke:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/ShareID" }
    post:
      tags: [Document Shares]
      summary: Irreversibly revoke an active public document share.
      operationId: revokeDocumentShare
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/branches:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Branches]
      summary: List document branches.
      operationId: listDocumentBranches
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Branches]
      summary: Create document branch.
      operationId: createDocumentBranch
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateBranchRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/branches/{branch_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/BranchID" }
    get:
      tags: [Branches]
      summary: Get document branch.
      operationId: getDocumentBranch
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    patch:
      tags: [Branches]
      summary: Update document branch.
      operationId: updateDocumentBranch
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchBranchRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/branches/{branch_id}/archive:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/BranchID" }
    post:
      tags: [Branches]
      summary: Archive document branch.
      operationId: archiveDocumentBranch
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Drafts]
      summary: List document drafts.
      operationId: listDocumentDrafts
      security: [{ JWTAuth: [] }]
      parameters:
        - { $ref: "#/components/parameters/BranchIDQuery" }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [Drafts]
      summary: Create document draft.
      operationId: createDocumentDraft
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DraftRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    get:
      tags: [Drafts]
      summary: Get document draft.
      operationId: getDocumentDraft
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    patch:
      tags: [Drafts]
      summary: Update document draft.
      operationId: updateDocumentDraft
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PatchDraftRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/content/{content_kind}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
      - { $ref: "#/components/parameters/ContentKind" }
    get:
      tags: [Drafts]
      summary: Get document draft content.
      description: Returns content, hash, and a nested draft DTO from the same snapshot. Use detail.draft.revision as expected_revision when saving edits, and detail.draft.review_revision as expected_review_revision when reviewing this content and its diff. Unpublished draft previews use the current branch latest as their baseline.
      operationId: getDocumentDraftContent
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/submit:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    post:
      tags: [Drafts]
      summary: Submit document draft.
      operationId: submitDocumentDraft
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/approve:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    post:
      tags: [Drafts]
      summary: Approve document draft.
      operationId: approveDocumentDraft
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ReviewRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/request-changes:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    post:
      tags: [Drafts]
      summary: Request document draft changes.
      operationId: requestDocumentDraftChanges
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ReviewRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/reject:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    post:
      tags: [Drafts]
      summary: Reject document draft.
      operationId: rejectDocumentDraft
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ReviewRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/promote:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    post:
      tags: [Drafts]
      summary: Promote document draft.
      operationId: promoteDocumentDraft
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PromoteDraftRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    get:
      tags: [Versions]
      summary: List published document versions.
      operationId: listDocumentVersions
      security: [{ JWTAuth: [] }]
      parameters:
        - { $ref: "#/components/parameters/BranchIDQuery" }
        - { $ref: "#/components/parameters/PageSizeQuery" }
        - { $ref: "#/components/parameters/OffsetQuery" }
        - { $ref: "#/components/parameters/SearchQuery" }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
    get:
      tags: [Versions]
      summary: Get published document version.
      operationId: getDocumentVersion
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}/content/{content_kind}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
      - { $ref: "#/components/parameters/ContentKind" }
    get:
      tags: [Versions]
      summary: Get document version content.
      operationId: getDocumentVersionContent
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}/endpoints:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
    get:
      tags: [Endpoints]
      summary: List endpoints indexed from a document version.
      operationId: listDocumentVersionEndpoints
      security: [{ JWTAuth: [] }]
      parameters:
        - { $ref: "#/components/parameters/PageSizeQuery" }
        - { $ref: "#/components/parameters/OffsetQuery" }
        - { $ref: "#/components/parameters/SearchQuery" }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}/endpoints/{endpoint_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
      - { $ref: "#/components/parameters/EndpointID" }
    get:
      tags: [Endpoints]
      summary: Get endpoint detail.
      operationId: getDocumentVersionEndpoint
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/diffs:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
    post:
      tags: [Diffs]
      summary: Compare document versions.
      description: Creates or returns a comparison only when the Project and Document are active and the two version IDs differ. Stored Diff history remains readable after archive.
      operationId: createDocumentDiff
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateDiffRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    get:
      tags: [Diffs]
      summary: List stored document diffs.
      description: Optional from_version_id and to_version_id query parameters select an exact version pair.
      operationId: listDocumentDiffs
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/diffs/{diff_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DiffID" }
    get:
      tags: [Diffs]
      summary: Get document diff.
      operationId: getDocumentDiff
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/diffs/{diff_id}/summary:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DiffID" }
    get:
      tags: [Diffs]
      summary: Get document diff summary.
      operationId: getDocumentDiffSummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/audit-logs:
    get:
      tags: [Audit Logs]
      summary: List authorized audit history.
      description: Super administrators may query all projects. Project administrators must supply project_id and can query only projects they administer. Reader and writer roles are denied. Results are newest first with at most 200 rows per page. Follow next_cursor to continue; has_more indicates whether a next page exists. A global total is omitted.
      operationId: listAuditLogs
      security: [{ JWTAuth: [] }]
      parameters:
        - {
            name: project_id,
            in: query,
            required: false,
            schema: { type: string },
          }
        - { name: action, in: query, required: false, schema: { type: string } }
        - {
            name: resource_type,
            in: query,
            required: false,
            schema: { type: string },
          }
        - {
            name: resource_id,
            in: query,
            required: false,
            schema: { type: string },
          }
        - {
            name: limit,
            in: query,
            required: false,
            schema: { type: integer, minimum: 1, maximum: 200, default: 100 },
          }
        - { name: cursor, in: query, schema: { type: string, maxLength: 512 }, description: Opaque next_cursor from the preceding page. Filters and authorization apply on every request. }
        - { name: from, in: query, schema: { type: string, format: date-time }, description: Inclusive lower time bound. }
        - { name: to, in: query, schema: { type: string, format: date-time }, description: Exclusive upper time bound. }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/ai/provider:
    get:
      tags: [AI]
      summary: Get system AI provider configuration.
      description: SuperAdmin only. Returns provider detail using AIProviderResponse. The response includes tuning fields temperature, timeout_ms, and max_output_tokens, plus redacted key state through api_key_set and api_key_last4.
      operationId: getSystemAIProvider
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    put:
      tags: [AI]
      summary: Upsert system AI provider configuration.
      description: SuperAdmin only. Saves an OpenAI-compatible provider. Omitted tuning fields use defaults from AIProviderRequest. The raw api_key is accepted only in the request and is never returned.
      operationId: putSystemAIProvider
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIProviderRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/ai/provider/test:
    post:
      tags: [AI]
      summary: Test the system AI provider without exposing its API key.
      description: SuperAdmin only. Tests the saved provider when the body is omitted, or tests the supplied AIProviderRequest without exposing the API key. Audit metadata records token usage when the provider returns usage fields and excludes secrets.
      operationId: testSystemAIProvider
      security: [{ JWTAuth: [] }]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIProviderRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/provider:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [AI]
      summary: Get project AI provider configuration.
      description: Project Admin or SuperAdmin only; Reader and Writer are denied even though they may use page summaries and chat where document permissions allow. Returns the project override using AIProviderResponse when configured. Historical configuration remains readable after project archive. Provider response fields include tuning values and redacted key metadata only.
      operationId: getProjectAIProvider
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
    put:
      tags: [AI]
      summary: Upsert project AI provider configuration.
      description: Project Admin or SuperAdmin only. Saves a project-level provider override for an active project with the same AIProviderRequest tuning defaults and ranges as the system provider. Archived project configuration cannot be changed.
      operationId: putProjectAIProvider
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIProviderRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/provider/test:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    post:
      tags: [AI]
      summary: Test the effective project AI provider.
      description: Project Admin or SuperAdmin only, and the project must be active. With no request body, tests the effective provider and falls back to the enabled system provider when no enabled project override exists. A request body supplies AIProviderRequest for a one-off project-scoped test. Reader and Writer are denied this configuration operation but may use page summaries and chat where document permissions allow.
      operationId: testProjectAIProvider
      security: [{ JWTAuth: [] }]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIProviderRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/ai/prompts:
    get:
      tags: [AI]
      summary: List effective system AI prompts.
      description: SuperAdmin only. Returns built-in prompts with any effective system overrides and the immutable AI guard appended.
      operationId: listSystemAIPrompts
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/ai/prompts/{prompt_key}:
    parameters:
      - { $ref: "#/components/parameters/AIPromptKey" }
    put:
      tags: [AI]
      summary: Upsert a system AI prompt override.
      description: SuperAdmin only. The path supplies prompt_key; the body supplies only editable prompt content. Every user_prompt_template must contain {{context}}, and page_chat must also contain {{message}}.
      operationId: putSystemAIPrompt
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIPromptRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/prompts:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [AI]
      summary: List effective project AI prompts.
      description: Project Admin or SuperAdmin only; Reader and Writer are denied even though they may use page summaries and chat where document permissions allow. Returns project overrides layered over system or built-in prompts. Historical prompt configuration remains readable after project archive.
      operationId: listProjectAIPrompts
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/prompts/{prompt_key}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/AIPromptKey" }
    put:
      tags: [AI]
      summary: Upsert a project AI prompt override.
      description: Project Admin or SuperAdmin only, and the project must be active. The path supplies prompt_key; the body supplies only editable prompt content. Every user_prompt_template must contain {{context}}, and page_chat must also contain {{message}}. Archived project prompt configuration cannot be changed.
      operationId: putProjectAIPrompt
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIPromptRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/ai-summary:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    get:
      tags: [AI]
      summary: Get an AI summary for a draft.
      operationId: getDraftAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/drafts/{draft_id}/ai-summary/regenerate:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DraftID" }
    post:
      tags: [AI]
      summary: Regenerate an AI summary for a draft.
      description: Queues a durable background generation and returns pending immediately (or skipped when no provider is configured). Poll the matching GET endpoint until succeeded, failed, or skipped. Repeated regeneration while pending reuses the existing job.
      operationId: regenerateDraftAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}/ai-summary:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
    get:
      tags: [AI]
      summary: Get an AI summary for a version.
      operationId: getVersionAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/versions/{version_id}/ai-summary/regenerate:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/VersionID" }
    post:
      tags: [AI]
      summary: Regenerate an AI summary for a version.
      description: Queues a durable background generation and returns pending immediately (or skipped when no provider is configured). Poll the matching GET endpoint until succeeded, failed, or skipped. Repeated regeneration while pending reuses the existing job.
      operationId: regenerateVersionAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/diffs/{diff_id}/ai-summary:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DiffID" }
    get:
      tags: [AI]
      summary: Get an AI summary for a diff.
      operationId: getDiffAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/documents/{document_id}/diffs/{diff_id}/ai-summary/regenerate:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/DocumentID" }
      - { $ref: "#/components/parameters/DiffID" }
    post:
      tags: [AI]
      summary: Regenerate an AI summary for a diff.
      description: Queues a durable background generation and returns pending immediately (or skipped when no provider is configured). Poll the matching GET endpoint until succeeded, failed, or skipped. Repeated regeneration while pending reuses the existing job.
      operationId: regenerateDiffAISummary
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/chat-sessions:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
    get:
      tags: [AI]
      summary: List AI chat sessions for an exact draft, version, or diff context.
      description: Returns retained sessions newest-updated first, including after the Project, Document, or target Branch is archived.
      operationId: listAIChatSessions
      security: [{ JWTAuth: [] }]
      parameters:
        - { $ref: "#/components/parameters/AIChatDocumentIDQuery" }
        - { $ref: "#/components/parameters/AIChatContextTypeQuery" }
        - { $ref: "#/components/parameters/AIChatContextIDQuery" }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [AI]
      summary: Create an AI chat session scoped to a draft, version, or diff.
      description: Requires an active Project, Document, and target Branch. Existing sessions remain readable after archive.
      operationId: createAIChatSession
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIChatSessionRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/chat-sessions/{session_id}:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/AIChatSessionID" }
    get:
      tags: [AI]
      summary: Get an AI chat session and messages.
      operationId: getAIChatSession
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/projects/{project_id}/ai/chat-sessions/{session_id}/messages:
    parameters:
      - { $ref: "#/components/parameters/ProjectID" }
      - { $ref: "#/components/parameters/AIChatSessionID" }
    post:
      tags: [AI]
      summary: Send a message in a page-scoped AI chat session.
      operationId: sendAIChatMessage
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIChatMessageRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/mcp-tokens:
    get:
      tags: [MCP Tokens]
      summary: List MCP tokens.
      operationId: listMCPTokens
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
    post:
      tags: [MCP Tokens]
      summary: Create MCP token.
      description: Returns a copyable token on create. At least one explicit scope is required, and expires_at must be in the future when supplied. The owner can reveal an active token again with the detail endpoint; list, revoked, and expired responses are redacted.
      operationId: createMCPToken
      security: [{ JWTAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateMCPTokenRequest" }
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/mcp-usage:
    get:
      tags: [MCP Tokens]
      summary: List sanitized MCP tool activity.
      description: Returns newest-first `mcp.tool_call` audit evidence for MCP tokens owned by the authenticated user. Supplying `token_id` selects one owned token; a SuperAdmin may use that parameter to inspect any user's token. Without `token_id`, even a SuperAdmin sees only activity for their own tokens. Results default to 100 and are capped at 200. Metadata is allowlisted to tool/adapter/result/reason plus referenced entity IDs and token ID. Entity IDs are retained only for successful tool calls, so caller-supplied IDs from failed requests cannot become entity evidence. IP address and User-Agent are removed, and raw token secrets, schemas, Markdown content, and request arguments are never returned.
      operationId: listMCPUsage
      security: [{ JWTAuth: [] }]
      parameters:
        - {
            name: token_id,
            in: query,
            required: false,
            schema: { type: string },
            description: MCP token ID. Non-SuperAdmins may select only a token they own.,
          }
        - {
            name: limit,
            in: query,
            required: false,
            schema: { type: integer, minimum: 1, maximum: 200, default: 100 },
          }
      responses:
        "200": { $ref: "#/components/responses/VdocListEnvelopeResponse" }
  /api/v1/private/mcp-tokens/{token_id}:
    parameters:
      - { $ref: "#/components/parameters/TokenID" }
    get:
      tags: [MCP Tokens]
      summary: Get MCP token.
      operationId: getMCPToken
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
  /api/v1/private/mcp-tokens/{token_id}/revoke:
    parameters:
      - { $ref: "#/components/parameters/TokenID" }
    post:
      tags: [MCP Tokens]
      summary: Revoke MCP token.
      operationId: revokeMCPToken
      security: [{ JWTAuth: [] }]
      responses:
        "200": { $ref: "#/components/responses/VdocEnvelopeResponse" }
components:
  securitySchemes:
    JWTAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Raw JWT string issued by login or register.
    MCPTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Raw MCP token string issued by the private MCP token APIs.
    DocumentShareAuth:
      type: apiKey
      in: header
      name: Authorization
      description: VdocShare scheme carrying the fragment-derived document-share capability. Protected links also require X-Vdoc-Share-Unlock after password exchange.
  parameters:
    PageSizeQuery:
      name: page_size
      in: query
      description: Opt in to server pagination. Omit for the legacy full-list response.
      schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
    OffsetQuery:
      name: offset
      in: query
      description: Number of matching rows to skip; requires page_size.
      schema: { type: integer, minimum: 0, maximum: 1000000, default: 0 }
    SearchQuery:
      name: search
      in: query
      description: Case-insensitive literal search; requires page_size. Maximum 256 UTF-8 bytes.
      schema: { type: string, maxLength: 256 }
    BranchIDQuery:
      name: branch_id
      in: query
      required: false
      schema: { type: string, format: uuid }
      description: Filter drafts or versions to one document branch.
    ProjectID:
      name: project_id
      in: path
      required: true
      schema: { type: string }
      description: Project ID.
    DocumentID:
      name: document_id
      in: path
      required: true
      schema: { type: string }
      description: Document ID.
    BranchID:
      name: branch_id
      in: path
      required: true
      schema: { type: string }
      description: Branch ID.
    DraftID:
      name: draft_id
      in: path
      required: true
      schema: { type: string }
      description: Draft ID.
    VersionID:
      name: version_id
      in: path
      required: true
      schema: { type: string }
      description: Published document version ID.
    ShareID:
      name: share_id
      in: path
      required: true
      schema:
        type: string
        pattern: "^[0-9a-f]{32}$"
      description: Public document share ID. The capability secret is never placed in this path.
    EndpointID:
      name: endpoint_id
      in: path
      required: true
      schema: { type: string }
      description: Parsed endpoint ID.
    DiffID:
      name: diff_id
      in: path
      required: true
      schema: { type: string }
      description: Diff ID.
    TokenID:
      name: token_id
      in: path
      required: true
      schema: { type: string }
      description: MCP token ID.
    UserID:
      name: user_id
      in: path
      required: true
      schema: { type: string }
      description: User ID.
    TeamID:
      name: team_id
      in: path
      required: true
      schema: { type: string }
      description: Team ID.
    ContentKind:
      name: content_kind
      in: path
      required: true
      schema:
        type: string
        enum: [raw, normalized, stable]
      description: Selects raw, normalized OpenAPI, or stable Markdown content.
    AIPromptKey:
      name: prompt_key
      in: path
      required: true
      schema:
        type: string
        enum:
          [
            draft_review_summary,
            version_change_summary,
            diff_change_summary,
            page_chat,
          ]
      description: AI prompt key.
    AIChatSessionID:
      name: session_id
      in: path
      required: true
      schema: { type: string }
      description: AI chat session ID.
    AIChatDocumentIDQuery:
      name: document_id
      in: query
      required: true
      schema: { type: string }
      description: Document ID for the exact AI page context.
    AIChatContextTypeQuery:
      name: context_type
      in: query
      required: true
      schema:
        type: string
        enum: [draft, version, diff]
      description: AI page context type.
    AIChatContextIDQuery:
      name: context_id
      in: query
      required: true
      schema: { type: string }
      description: Draft, version, or Diff ID for the exact AI page context.
  responses:
    VdocEnvelopeResponse:
      description: HTTP 200 response with Vdoc envelope.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/VdocEnvelope" }
    VdocListEnvelopeResponse:
      description: HTTP 200 response with Vdoc envelope and total count.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/VdocListEnvelope" }
    OpenAPISpecResponse:
      description: Checked-in OpenAPI YAML bytes.
      content:
        application/yaml:
          schema: { type: string }
    MCPJSONRPCResponse:
      description: HTTP 200 response containing a JSON-RPC success or error object.
      content:
        application/json:
          schema: { type: object }
    PublicDocumentDownloadResponse:
      description: Authorized immutable raw OpenAPI or Markdown bytes with an attachment Content-Disposition header.
      headers:
        Content-Disposition:
          schema: { type: string }
      content:
        application/json:
          schema: { type: string, format: binary }
        application/yaml:
          schema: { type: string, format: binary }
        text/markdown:
          schema: { type: string, format: binary }
  schemas:
    VdocEnvelope:
      type: object
      properties:
        code: { type: integer }
        status: { type: string }
        description: { type: string }
        message: { type: string }
        trace_id: { type: string }
        timestamp: { type: integer }
        detail: {}
    VdocListEnvelope:
      allOf:
        - { $ref: "#/components/schemas/VdocEnvelope" }
        - type: object
          properties:
            total: { type: integer, description: Total matches for offset pagination; omitted for audit cursor pages. }
            has_more: { type: boolean }
            next_cursor: { type: string, description: Present when another cursor page is available. }
    AuthRequest:
      type: object
      additionalProperties: false
      required: [email, password]
      properties:
        email: { type: string, format: email }
        name: { type: string }
        password:
          type: string
          format: password
          description: UTF-8 encoding must be 12 to 72 bytes with no leading or trailing whitespace.
    MCPCallRequest:
      type: object
      description: JSON-RPC 2.0 tools/list or tools/call request, or the documented legacy tool bridge object.
      properties:
        jsonrpc: { type: string, const: "2.0" }
        id: {}
        method: { type: string, enum: [tools/list, tools/call] }
        params: { type: object }
        tool: { $ref: "#/components/schemas/MCPToolName" }
        arguments: { type: object }
    DocumentShareUnlockRequest:
      type: object
      additionalProperties: false
      required: [password]
      properties:
        password: { type: string, minLength: 1 }
    CreateUserRequest:
      type: object
      additionalProperties: false
      required: [email, name, password, is_super_admin]
      properties:
        email: { type: string, format: email }
        name: { type: string }
        password:
          type: string
          format: password
          description: UTF-8 encoding must be 12 to 72 bytes with no leading or trailing whitespace.
        is_super_admin: { type: boolean }
    PatchUserRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        status: { type: integer, enum: [1, 2] }
        is_super_admin: { type: boolean }
    NameDescriptionRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name: { type: string, minLength: 1 }
        description: { type: string }
    PatchNameDescriptionRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name: { type: string, minLength: 1 }
        description: { type: string }
    CreateProjectRequest:
      type: object
      additionalProperties: false
      required: [team_id, name]
      properties:
        team_id: { type: string }
        name: { type: string, minLength: 1 }
        description: { type: string }
        admin_user_id:
          type: string
          description: Optional active user to assign as initial Project Admin; omitted or blank selects the acting SuperAdmin.
    AddProjectMemberRequest:
      type: object
      additionalProperties: false
      required: [user_id, role]
      properties:
        user_id: { type: string }
        role: { type: integer, enum: [1, 2, 3] }
    PatchProjectMemberRoleRequest:
      type: object
      additionalProperties: false
      required: [role]
      properties:
        role: { type: integer, enum: [1, 2, 3] }
    DocumentRequest:
      type: object
      additionalProperties: false
      required: [name, document_type, relative_path]
      properties:
        name: { type: string, minLength: 1 }
        document_type: { type: integer, enum: [1, 2] }
        relative_path: { type: string, minLength: 1 }
        description: { type: string }
    PatchDocumentRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name: { type: string, minLength: 1 }
        relative_path: { type: string, minLength: 1 }
        description: { type: string }
    CreateDocumentShareRequest:
      type: object
      additionalProperties: false
      required: [branch_id, version_scope, expiry_preset]
      properties:
        branch_id: { type: string }
        version_scope: { type: integer, enum: [1, 2] }
        expiry_preset:
          type: string
          enum: [1_month, 3_months, 6_months, 1_year, permanent]
        password: { type: string }
    CreateBranchRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name:
          type: string
          pattern: "^(dev|test|prod|feature/.+)$"
        description: { type: string }
    PatchBranchRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          pattern: "^(dev|test|prod|feature/.+)$"
        description: { type: string }
        is_default: { type: boolean }
        is_protected: { type: boolean }
    DraftRequest:
      type: object
      additionalProperties: false
      required: [branch_id, version_name]
      anyOf:
        - required: [schema_content]
        - required: [content]
      properties:
        branch_id: { type: string }
        version_name: { type: string, minLength: 1 }
        changelog: { type: string }
        source_git_commit_id: { type: string }
        schema_content:
          type: string
          description: OpenAPI source content. The handler also accepts this field for Markdown clients.
        content:
          type: string
          description: Markdown source content; used when schema_content is empty.
    PatchDraftRequest:
      type: object
      additionalProperties: false
      required: [expected_revision]
      anyOf:
        - required: [schema_content]
        - required: [content]
      properties:
        expected_revision:
          type: string
          minLength: 1
          description: Opaque revision returned with the draft snapshot. Stale revisions fail with FAILED_PRECONDITION; reload and reconcile edits before retrying.
        version_name: { type: string, minLength: 1 }
        changelog: { type: string }
        source_git_commit_id: { type: string }
        schema_content:
          type: string
          description: Updated OpenAPI source content. The handler also accepts this field for Markdown clients.
        content:
          type: string
          description: Updated Markdown source content; used when schema_content is empty.
    ReviewRequest:
      type: object
      additionalProperties: false
      required: [expected_review_revision]
      properties:
        expected_review_revision:
          type: string
          minLength: 1
          description: Opaque detail.draft.review_revision from the content snapshot the reviewer inspected. Binds content, submission round, and latest branch diff baseline. Stale snapshots return FAILED_PRECONDITION; reload and review again before retrying.
        comment: { type: string, maxLength: 1000 }
    PromoteDraftRequest:
      type: object
      additionalProperties: false
      required: [source_branch_id, target_branch_id, version_name]
      properties:
        source_branch_id: { type: string }
        target_branch_id: { type: string }
        version_name: { type: string, minLength: 1 }
        changelog: { type: string }
    CreateDiffRequest:
      type: object
      additionalProperties: false
      required: [from_version_id, to_version_id]
      properties:
        from_version_id: { type: string }
        to_version_id: { type: string }
    AIChatSessionRequest:
      type: object
      additionalProperties: false
      required: [document_id, context_type, context_id]
      properties:
        document_id: { type: string }
        context_type: { type: string, enum: [draft, version, diff] }
        context_id: { type: string }
        title: { type: string }
    AIChatMessageRequest:
      type: object
      additionalProperties: false
      required: [content]
      properties:
        content: { type: string, minLength: 1, maxLength: 4000 }
    CreateMCPTokenRequest:
      type: object
      additionalProperties: false
      required: [name, scopes]
      properties:
        name: { type: string, minLength: 1 }
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items: { type: integer, enum: [1, 2, 3, 4] }
        expires_at:
          type: string
          format: date-time
          description: Optional expiry strictly later than the backend's current time.
    AIProviderRequest:
      type: object
      additionalProperties: false
      required: [name, base_url, model, api_mode, enabled]
      properties:
        name:
          type: string
          description: Human-readable provider name.
        base_url:
          type: string
          format: uri
          description: OpenAI-compatible base URL. The backend normalizes it to the supported API path for the selected api_mode.
        model:
          type: string
          description: Provider model name sent to the upstream provider.
        api_mode:
          type: string
          enum: [chat_completions, responses]
          description: Selects OpenAI chat completions payloads or OpenAI responses payloads.
        api_key:
          type: string
          writeOnly: true
          description: Raw provider API key. It is encrypted for storage and never returned by API responses or audit metadata.
        enabled:
          type: boolean
          description: Whether this provider can be used for summaries and chat.
        temperature:
          type: number
          format: double
          default: 0.2
          minimum: 0
          maximum: 2
          description: Sampling temperature. Omit to use 0.2. Values from 0 through 2 are accepted.
        timeout_ms:
          type: integer
          default: 30000
          minimum: 1000
          maximum: 120000
          description: Provider request timeout in milliseconds. Omit to use 30000. Values from 1000 through 120000 are accepted.
        max_output_tokens:
          type: integer
          default: 1000
          minimum: 1
          maximum: 32000
          description: Maximum generated output tokens. Omit to use 1000. Values from 1 through 32000 are accepted.
    AIProviderResponse:
      type: object
      additionalProperties: false
      required:
        [api_key_set, enabled, temperature, timeout_ms, max_output_tokens]
      properties:
        id: { type: string }
        scope:
          type: string
          enum: [system, project]
        project_id: { type: string }
        name: { type: string }
        base_url: { type: string }
        model: { type: string }
        api_mode:
          type: string
          enum: [chat_completions, responses]
        api_key_set:
          type: boolean
          description: True when an encrypted provider API key is stored.
        api_key_last4:
          type: string
          description: Last four characters of the stored provider key, returned for operator confirmation only.
        enabled: { type: boolean }
        temperature:
          type: number
          format: double
          default: 0.2
          minimum: 0
          maximum: 2
          description: Effective sampling temperature.
        timeout_ms:
          type: integer
          default: 30000
          minimum: 1000
          maximum: 120000
          description: Effective provider timeout in milliseconds.
        max_output_tokens:
          type: integer
          default: 1000
          minimum: 1
          maximum: 32000
          description: Effective output token cap.
    AIPromptRequest:
      type: object
      additionalProperties: false
      required: [system_prompt, user_prompt_template, enabled]
      properties:
        system_prompt:
          type: string
          minLength: 1
          description: Non-blank operator prompt. The backend appends an immutable guard that prevents AI review or publication actions.
        user_prompt_template:
          type: string
          minLength: 1
          description: Non-blank template. Every prompt key requires the literal {{context}} placeholder; page_chat additionally requires the literal {{message}} placeholder.
        enabled:
          type: boolean
          description: Whether this prompt can be used. A disabled summary prompt records generation as skipped without blocking draft submission or version publishing.
    AIProviderTestResult:
      type: object
      additionalProperties: false
      required: [ok, content]
      properties:
        ok: { type: boolean }
        content:
          type: string
          description: Provider connectivity check response text.
    AISummaryResponse:
      type: object
      additionalProperties: false
      required:
        [
          id,
          project_id,
          document_id,
          owner_type,
          owner_id,
          prompt_key,
          status,
          generated_by,
          generated_at,
          updated_at,
        ]
      properties:
        id: { type: string }
        project_id: { type: string }
        document_id: { type: string }
        owner_type:
          type: string
          enum: [draft, version, diff]
        owner_id: { type: string }
        prompt_key:
          type: string
          enum:
            [draft_review_summary, version_change_summary, diff_change_summary]
        provider_id: { type: string }
        status:
          type: string
          enum: [pending, skipped, succeeded, failed]
          description: pending marks the latest in-flight request; skipped and failed records are persisted for diagnostics and do not block draft submit or version publish.
        content: { type: string }
        error_message:
          type: string
          description: Non-secret provider, prompt, or configuration failure summary for skipped and failed records.
        generated_by: { type: string }
        generated_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    MCPToolName:
      type: string
      enum:
        - list_projects
        - list_documents
        - list_document_branches
        - list_api_endpoints
        - list_api_versions
        - list_doc_versions
        - get_latest_schema
        - get_endpoint_detail
        - compare_api_versions
        - get_change_summary
        - create_api_version_draft
        - update_api_version_draft
        - submit_api_version_draft
        - get_api_version_draft
        - get_latest_doc
        - compare_doc_versions
        - create_doc_draft
        - update_doc_draft
        - submit_doc_draft
        - get_doc_draft