openapi: 3.1.0
info:
  title: AllSign Public API
  version: 0.1.0
  summary: Canonical bearer-token REST API for public integrations.
servers:
  - url: /api
security:
  - bearerAuth: []
tags:
  - name: Actors
  - name: Agreements
  - name: Attachments
  - name: Comments
  - name: Contacts
  - name: Imports
  - name: Participants
  - name: Settings
  - name: Signing
  - name: Templates
paths:
  /actors/self:
    get:
      tags:
        - Actors
      summary: Get the authenticated actor
      operationId: getActorSelf
      description: Returns the bearer-authenticated actor identity resolved for the current API request.
      responses:
        "200":
          description: Authenticated actor summary.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - actor
                    properties:
                      actor:
                        $ref: "#/components/schemas/Actor"
        "401":
          $ref: "#/components/responses/Error"
  /contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      operationId: listContacts
      description: Returns a paginated canonical contact collection owned by the authenticated actor.
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - name: search
          in: query
          required: false
          description: Filters contacts by canonical searchable fields.
          schema:
            type: string
      responses:
        "200":
          description: Paginated contact list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - contacts
                        properties:
                          contacts:
                            type: array
                            items:
                              $ref: "#/components/schemas/Contact"
        "401":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Contacts
      summary: Create a contact
      operationId: createContact
      description: Creates a canonical contact owned by the authenticated actor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactCreate"
      responses:
        "201":
          description: Contact created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - contact
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements:
    get:
      tags:
        - Agreements
      summary: List agreements
      operationId: listAgreements
      description: Returns a paginated canonical agreement collection visible to the authenticated actor.
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - name: search
          in: query
          required: false
          description: Filters agreements by canonical searchable fields.
          schema:
            type: string
      responses:
        "200":
          description: Paginated agreement list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - agreements
                        properties:
                          agreements:
                            type: array
                            items:
                              $ref: "#/components/schemas/AgreementPartial"
              examples:
                example:
                  summary: Paginated list of agreements
                  value:
                    data:
                      page: 1
                      page_size: 20
                      total_pages: 1
                      total_records: 1
                      agreements:
                        - ref: "a1b2c3d4-0001-4000-8000-000000000001"
                          name: "PRD: Enterprise Data Export v1"
                          description: null
                          intent: binding
                          status: executed
        "401":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Agreements
      summary: Create an agreement
      operationId: createAgreement
      description: Creates a canonical agreement owned by the authenticated actor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementCreate"
            examples:
              example:
                summary: Create a binding agreement
                value:
                  name: "PRD: Enterprise Data Export v1"
                  intent: binding
                  priority: high
      responses:
        "201":
          description: Agreement created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
              examples:
                example:
                  summary: Agreement created
                  value:
                    data:
                      agreement:
                        ref: "a1b2c3d4-0001-4000-8000-000000000001"
                        name: "PRD: Enterprise Data Export v1"
                        description: null
                        intent: binding
                        priority: high
                        status: draft
                        executed_at: null
                        rejected_at: null
                        rejected_reason: null
                        requires_2fa: false
                        requires_rcp: false
                        sections: []
                        terms: []
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}:
    get:
      tags:
        - Agreements
      summary: Get an agreement
      operationId: getAgreement
      description: Returns a canonical agreement identified by agreement reference.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "200":
          description: Agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
              examples:
                example:
                  summary: Executed agreement
                  value:
                    data:
                      agreement:
                        ref: "a1b2c3d4-0001-4000-8000-000000000001"
                        name: "PRD: Enterprise Data Export v1"
                        description: null
                        intent: binding
                        priority: high
                        status: executed
                        executed_at: "2026-06-27T15:30:00Z"
                        rejected_at: null
                        rejected_reason: null
                        requires_2fa: false
                        requires_rcp: false
                        sections:
                          - ref: "a1b2c3d4-0011-4000-8000-000000000001"
                            name: Problem Statement
                            description: null
                            position: 1
                            terms: []
                          - ref: "a1b2c3d4-0013-4000-8000-000000000001"
                            name: v1 Scope
                            description: null
                            position: 3
                            terms:
                              - ref: "a1b2c3d4-0031-4000-8000-000000000001"
                                name: "Export Formats"
                                description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                                negotiable: true
                                locked: true
                                pending_counter_proposal: false
                                has_review_history: true
                                priority: medium
                                position: 1
                        terms:
                          - ref: "a1b2c3d4-0031-4000-8000-000000000001"
                            name: "Export Formats"
                            description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                            negotiable: true
                            locked: true
                            pending_counter_proposal: false
                            has_review_history: true
                            priority: medium
                            position: 1
                          - ref: "a1b2c3d4-0034-4000-8000-000000000001"
                            name: "Link Validity"
                            description: "Download links valid for 14 days from generation."
                            negotiable: true
                            locked: true
                            pending_counter_proposal: false
                            has_review_history: true
                            priority: medium
                            position: 2
                          - ref: "a1b2c3d4-0063-4000-8000-000000000001"
                            name: "Completion Notification"
                            description: "In-app notification only for v1; email after notification redesign ships."
                            negotiable: true
                            locked: true
                            pending_counter_proposal: false
                            has_review_history: true
                            priority: medium
                            position: 3
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    put:
      tags:
        - Agreements
      summary: Update an agreement
      operationId: updateAgreement
      description: Updates a canonical agreement identified by agreement reference.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementUpdate"
      responses:
        "200":
          description: Updated agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Agreements
      summary: Delete an agreement
      operationId: deleteAgreement
      description: Deletes a canonical agreement and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "200":
          description: Deleted agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/rejections:
    post:
      tags:
        - Agreements
      summary: Reject an agreement
      operationId: createAgreementRejection
      description: Records a rejection event for the referenced agreement and returns the final agreement representation.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementTermination"
      responses:
        "200":
          description: Rejected agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/cancellations:
    post:
      tags:
        - Agreements
      summary: Cancel an agreement
      operationId: createAgreementCancellation
      description: Records a cancellation event for the referenced agreement and returns the final agreement representation.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementTermination"
      responses:
        "200":
          description: Cancelled agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/copies:
    post:
      tags:
        - Agreements
      summary: Create an agreement copy
      operationId: createAgreementCopy
      description: Creates a canonical agreement copy from the referenced agreement and returns the copied agreement representation.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "201":
          description: Copied agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /contacts/{contact_ref}:
    get:
      tags:
        - Contacts
      summary: Get a contact
      operationId: getContact
      description: Returns a canonical contact identified by contact reference.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      responses:
        "200":
          description: Contact representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - contact
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    put:
      tags:
        - Contacts
      summary: Update a contact
      operationId: updateContact
      description: Updates a canonical contact identified by contact reference.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactUpdate"
      responses:
        "200":
          description: Updated contact representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - contact
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Contacts
      summary: Delete a contact
      operationId: deleteContact
      description: Deletes a canonical contact and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      responses:
        "200":
          description: Deleted contact representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - contact
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /templates:
    get:
      tags:
        - Templates
      summary: List templates
      operationId: listTemplates
      description: Returns a paginated canonical template collection owned by the authenticated actor.
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - name: search
          in: query
          required: false
          description: Filters templates by canonical searchable fields.
          schema:
            type: string
      responses:
        "200":
          description: Paginated template list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - templates
                        properties:
                          templates:
                            type: array
                            items:
                              $ref: "#/components/schemas/TemplatePartial"
        "401":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Templates
      summary: Create a template
      operationId: createTemplate
      description: Creates a canonical template owned by the authenticated actor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateCreate"
      responses:
        "201":
          description: Template created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - template
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/templates:
    post:
      tags:
        - Templates
      summary: Create a template from an agreement
      operationId: createTemplateFromAgreement
      description: Creates a canonical template from the referenced agreement and returns the new template representation.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "201":
          description: Created template representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - template
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}:
    get:
      tags:
        - Templates
      summary: Get a template
      operationId: getTemplate
      description: Returns a canonical template identified by template reference.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "200":
          description: Template representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - template
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    put:
      tags:
        - Templates
      summary: Update a template
      operationId: updateTemplate
      description: Updates a canonical template identified by template reference.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateUpdate"
      responses:
        "200":
          description: Updated template representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - template
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Templates
      summary: Delete a template
      operationId: deleteTemplate
      description: Deletes a canonical template and returns a success confirmation.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "200":
          description: Deleted template confirmation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - deleted
                      - ref
                    properties:
                      deleted:
                        type: boolean
                        enum:
                          - true
                      ref:
                        type: string
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/copies:
    post:
      tags:
        - Templates
      summary: Create a template copy
      operationId: createTemplateCopy
      description: Creates a canonical template copy from the referenced template and returns the copied template representation.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "201":
          description: Copied template representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - template
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/agreements:
    post:
      tags:
        - Agreements
      summary: Create an agreement from a template
      operationId: createAgreementFromTemplate
      description: Creates a canonical agreement from the referenced template and returns the new agreement representation.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "201":
          description: Created agreement representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - agreement
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/participants:
    get:
      tags:
        - Participants
      summary: List participants
      operationId: listAgreementParticipants
      description: Returns a paginated canonical participant collection for an agreement visible to the authenticated actor.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated participant list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - participants
                        properties:
                          participants:
                            type: array
                            items:
                              $ref: "#/components/schemas/Participant"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Participants
      summary: Create a participant
      operationId: createAgreementParticipant
      description: Creates an agreement participant invitation or an active agent participant for the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParticipantCreate"
            examples:
              example:
                summary: Invite a participant as signer
                value:
                  email: marcus.webb@lumen.app
                  name: Marcus Webb
                  type: signer
      responses:
        "201":
          description: Participant created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - invitation
                      - participant
                    properties:
                      invitation:
                        anyOf:
                          - $ref: "#/components/schemas/InvitationPartial"
                          - type: "null"
                      participant:
                        $ref: "#/components/schemas/Participant"
              examples:
                example:
                  summary: Participant invited as signer
                  value:
                    data:
                      participant:
                        ref: "a1b2c3d4-0102-4000-8000-000000000001"
                        name: Marcus Webb
                        email: marcus.webb@lumen.app
                        type: signer
                        active: false
                        avatar_url: null
                        actor: null
                      invitation:
                        ref: "a1b2c3d4-0501-4000-8000-000000000001"
                        email: marcus.webb@lumen.app
                        type: signer
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/participants/self:
    post:
      tags:
        - Participants
      summary: Create a self-join participant
      operationId: createAgreementParticipantSelf
      description: Creates a canonical active participant for the authenticated actor on the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParticipantSelfJoinCreate"
      responses:
        "201":
          description: Participant created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - participant
                    properties:
                      participant:
                        $ref: "#/components/schemas/Participant"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /participants/{participant_ref}:
    put:
      tags:
        - Participants
      summary: Update a participant
      operationId: updateParticipant
      description: Updates the canonical role assignment for an identified agreement participant.
      parameters:
        - $ref: "#/components/parameters/ParticipantRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParticipantUpdate"
      responses:
        "200":
          description: Updated participant representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - participant
                    properties:
                      participant:
                        $ref: "#/components/schemas/Participant"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Participants
      summary: Delete a participant
      operationId: deleteParticipant
      description: Deletes a canonical participant and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/ParticipantRef"
      responses:
        "200":
          description: Deleted participant representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - participant
                    properties:
                      participant:
                        $ref: "#/components/schemas/Participant"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /invitations/{invitation_ref}/accepts:
    post:
      tags:
        - Participants
      summary: Create an invitation accept
      operationId: createInvitationAccept
      description: Accepts the identified invitation and returns the activated participant representation.
      parameters:
        - $ref: "#/components/parameters/InvitationRef"
      responses:
        "200":
          description: Accepted participant representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - participant
                    properties:
                      participant:
                        $ref: "#/components/schemas/Participant"
              examples:
                example:
                  summary: Accepted participant invitation
                  value:
                    data:
                      participant:
                        ref: "a1b2c3d4-0102-4000-8000-000000000001"
                        name: Marcus Webb
                        email: marcus.webb@lumen.app
                        type: signer
                        active: true
                        avatar_url: null
                        actor:
                          ref: "a1b2c3d4-0602-4000-8000-000000000001"
                          kind: user
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /invitations/{invitation_ref}/rejects:
    post:
      tags:
        - Participants
      summary: Create an invitation reject
      operationId: createInvitationReject
      description: Rejects the identified invitation and returns the rejected invitation reference.
      parameters:
        - $ref: "#/components/parameters/InvitationRef"
      responses:
        "200":
          description: Rejected invitation reference.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - invitation
                    properties:
                      invitation:
                        $ref: "#/components/schemas/InvitationReference"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/sections:
    post:
      tags:
        - Agreements
      summary: Create a section
      operationId: createAgreementSection
      description: Creates a canonical section under the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SectionCreate"
            examples:
              example:
                summary: Create a section
                value:
                  name: v1 Scope
                  position: 3
      responses:
        "201":
          description: Section created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
              examples:
                example:
                  summary: Section created
                  value:
                    data:
                      section:
                        ref: "a1b2c3d4-0013-4000-8000-000000000001"
                        name: v1 Scope
                        description: null
                        position: 3
                        terms: []
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/sections:
    post:
      tags:
        - Templates
      summary: Create a section
      operationId: createTemplateSection
      description: Creates a canonical section under the identified template.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SectionCreate"
      responses:
        "201":
          description: Section created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /sections/{section_ref}:
    put:
      tags:
        - Agreements
      summary: Update a section
      operationId: updateSection
      description: Updates a canonical section identified by section reference.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SectionUpdate"
      responses:
        "200":
          description: Updated section representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /sections/{section_ref}/copies:
    post:
      tags:
        - Agreements
      summary: Create a section copy
      operationId: createSectionCopy
      description: Creates a canonical copy of the identified section and returns the copied section representation.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
      responses:
        "201":
          description: Copied section representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /sections/{section_ref}/placements:
    post:
      tags:
        - Agreements
      summary: Create a section placement
      operationId: createSectionPlacement
      description: Repositions a canonical section and returns the updated section representation.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlacementCreate"
      responses:
        "200":
          description: Repositioned section representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Agreements
      summary: Delete a section
      operationId: deleteSection
      description: Deletes a canonical section and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
      responses:
        "200":
          description: Deleted section representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - section
                    properties:
                      section:
                        $ref: "#/components/schemas/Section"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/terms:
    post:
      tags:
        - Agreements
      summary: Create a term
      operationId: createAgreementTerm
      description: Creates a canonical term under the identified agreement, optionally nested under a section.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TermCreate"
            examples:
              example:
                summary: Create a term within a section
                value:
                  name: "Export Formats"
                  description: "Export formats supported at launch: CSV, JSON, and PDF."
                  negotiable: true
                  section:
                    ref: "a1b2c3d4-0013-4000-8000-000000000001"
                  priority: medium
                  position: 1
      responses:
        "201":
          description: Term created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
              examples:
                example:
                  summary: Term created within a section
                  value:
                    data:
                      term:
                        ref: "a1b2c3d4-0031-4000-8000-000000000001"
                        name: "Export Formats"
                        description: "Export formats supported at launch: CSV, JSON, and PDF."
                        negotiable: true
                        locked: false
                        pending_counter_proposal: false
                        has_review_history: false
                        priority: medium
                        position: 1
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/terms:
    post:
      tags:
        - Templates
      summary: Create a term
      operationId: createTemplateTerm
      description: Creates a canonical term under the identified template, optionally nested under a section.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TermCreate"
      responses:
        "201":
          description: Term created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}:
    put:
      tags:
        - Agreements
      summary: Update a term
      operationId: updateTerm
      description: Updates a canonical term identified by term reference.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TermUpdate"
      responses:
        "200":
          description: Updated term representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Agreements
      summary: Delete a term
      operationId: deleteTerm
      description: Deletes a canonical term and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      responses:
        "200":
          description: Deleted term representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/copies:
    post:
      tags:
        - Agreements
      summary: Create a term copy
      operationId: createTermCopy
      description: Creates a canonical copy of the identified term and returns the copied term representation.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      responses:
        "201":
          description: Copied term representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/conditions:
    post:
      tags:
        - Agreements
      summary: Create a term condition
      operationId: createTermCondition
      description: Updates the canonical negotiability condition of a term and returns the updated term representation.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TermConditionChange"
      responses:
        "200":
          description: Updated term representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/placements:
    post:
      tags:
        - Agreements
      summary: Create a term placement
      operationId: createTermPlacement
      description: Repositions a canonical term and returns the updated term representation.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlacementCreate"
      responses:
        "200":
          description: Repositioned term representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - term
                    properties:
                      term:
                        $ref: "#/components/schemas/Term"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/decisions:
    get:
      tags:
        - Decisions
      summary: List term decisions
      operationId: listTermDecisions
      description: Returns a paginated canonical decision collection scoped to a term.
      parameters:
        - $ref: "#/components/parameters/TermRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated term decision list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - decisions
                        properties:
                          decisions:
                            type: array
                            items:
                              $ref: "#/components/schemas/Decision"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Decisions
      summary: Create a term decision
      operationId: createTermDecision
      description: Creates a canonical decision for the current revision of the identified term.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DecisionCreate"
            examples:
              example:
                summary: Accept the current term revision
                value:
                  status: accepted
                  remarks: "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline."
      responses:
        "201":
          description: Decision created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - decision
                      - proposal_decision
                      - revision
                    properties:
                      decision:
                        $ref: "#/components/schemas/Decision"
                      proposal_decision:
                        anyOf:
                          - $ref: "#/components/schemas/Decision"
                          - type: "null"
                      revision:
                        anyOf:
                          - $ref: "#/components/schemas/Revision"
                          - type: "null"
              examples:
                example:
                  summary: Term revision accepted
                  value:
                    data:
                      decision:
                        ref: "a1b2c3d4-0401-4000-8000-000000000001"
                        status: accepted
                        remarks: "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline."
                        created_at: "2026-06-27T11:00:00Z"
                        actor:
                          ref: "a1b2c3d4-0601-4000-8000-000000000001"
                          name: Priya Nair
                          avatar_url: null
                        revision:
                          ref: "a1b2c3d4-0301-4000-8000-000000000001"
                      proposal_decision: null
                      revision: null
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/revisions:
    get:
      tags:
        - Revisions
      summary: List term revisions
      operationId: listTermRevisions
      description: Returns a paginated canonical revision collection scoped to a term.
      parameters:
        - $ref: "#/components/parameters/TermRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated term revision list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - revisions
                        properties:
                          revisions:
                            type: array
                            items:
                              $ref: "#/components/schemas/Revision"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Revisions
      summary: Create a term revision
      operationId: createTermRevision
      description: Creates a canonical revision proposal for the identified term and records its accepting decision.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevisionProposal"
              examples:
                example:
                  summary: Propose a term revision
                  value:
                    description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                    remarks: "PDF export is out of scope for v1; deferring to reduce launch risk."
      responses:
        "201":
          description: Revision created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - decision
                      - revision
                    properties:
                      decision:
                        $ref: "#/components/schemas/Decision"
                      revision:
                        $ref: "#/components/schemas/Revision"
              examples:
                example:
                  summary: Term revision recorded
                  value:
                    data:
                      revision:
                        ref: "a1b2c3d4-0301-4000-8000-000000000001"
                        number: 1
                        description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                        name: null
                        latest: true
                        created_at: "2026-06-27T10:30:00Z"
                        actor:
                          ref: "a1b2c3d4-0602-4000-8000-000000000001"
                          name: Marcus Webb
                        decisions: []
                      decision:
                        ref: "a1b2c3d4-0401-4000-8000-000000000001"
                        status: accepted
                        remarks: "PDF export is out of scope for v1; deferring to reduce launch risk."
                        created_at: "2026-06-27T10:30:00Z"
                        actor:
                          ref: "a1b2c3d4-0602-4000-8000-000000000001"
                          name: Marcus Webb
                          avatar_url: null
                        revision:
                          ref: "a1b2c3d4-0301-4000-8000-000000000001"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/comments:
    get:
      tags:
        - Comments
      summary: List agreement comments
      operationId: listAgreementComments
      description: Returns a paginated canonical comment collection scoped to an agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated agreement comment list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - comments
                        properties:
                          comments:
                            type: array
                            items:
                              $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Comments
      summary: Create an agreement comment
      operationId: createAgreementComment
      description: Creates a canonical comment scoped directly to an agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentCreate"
      responses:
        "201":
          description: Comment created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - comment
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /sections/{section_ref}/comments:
    get:
      tags:
        - Comments
      summary: List section comments
      operationId: listSectionComments
      description: Returns a paginated canonical comment collection scoped to a section.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated section comment list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - comments
                        properties:
                          comments:
                            type: array
                            items:
                              $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Comments
      summary: Create a section comment
      operationId: createSectionComment
      description: Creates a canonical comment scoped to a section.
      parameters:
        - $ref: "#/components/parameters/SectionRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentCreate"
      responses:
        "201":
          description: Comment created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - comment
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /terms/{term_ref}/comments:
    get:
      tags:
        - Comments
      summary: List term comments
      operationId: listTermComments
      description: Returns a paginated canonical comment collection scoped to a term.
      parameters:
        - $ref: "#/components/parameters/TermRef"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Paginated term comment list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    allOf:
                      - $ref: "#/components/schemas/Pagination"
                      - type: object
                        required:
                          - comments
                        properties:
                          comments:
                            type: array
                            items:
                              $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Comments
      summary: Create a term comment
      operationId: createTermComment
      description: Creates a canonical comment scoped to a term and optionally pinned to the current revision.
      parameters:
        - $ref: "#/components/parameters/TermRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentCreate"
      responses:
        "201":
          description: Comment created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - comment
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /comments/{comment_ref}:
    put:
      tags:
        - Comments
      summary: Update a comment
      operationId: updateComment
      description: Updates a canonical comment identified by comment reference.
      parameters:
        - $ref: "#/components/parameters/CommentRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentUpdate"
      responses:
        "200":
          description: Updated comment representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - comment
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "409":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Comments
      summary: Delete a comment
      operationId: deleteComment
      description: Deletes a canonical comment and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/CommentRef"
      responses:
        "200":
          description: Deleted comment representation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - comment
                    properties:
                      comment:
                        $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /settings:
    get:
      tags:
        - Settings
      summary: Get actor settings
      operationId: getActorSettings
      description: Returns notification preferences and security context for the bearer-authenticated actor.
      responses:
        "200":
          description: Authenticated actor settings.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [settings]
                    properties:
                      settings:
                        $ref: "#/components/schemas/Settings"
        "401":
          $ref: "#/components/responses/Error"
    put:
      tags:
        - Settings
      summary: Update actor settings
      operationId: updateActorSettings
      description: Updates notification preferences for the bearer-authenticated actor and returns the current settings view.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationSettingsUpdate"
      responses:
        "200":
          description: Updated actor settings.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [settings]
                    properties:
                      settings:
                        $ref: "#/components/schemas/Settings"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /actors/self/avatar:
    put:
      tags:
        - Actors
      summary: Replace the authenticated actor avatar
      operationId: replaceActorAvatar
      description: Stores avatar media for the bearer-authenticated actor and returns the updated actor representation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvatarUpload"
      responses:
        "200":
          description: Updated actor representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [actor]
                    properties:
                      actor:
                        $ref: "#/components/schemas/Actor"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Actors
      summary: Delete the authenticated actor avatar
      operationId: deleteActorAvatar
      description: Deletes avatar media for the bearer-authenticated actor and returns the updated actor representation.
      responses:
        "200":
          description: Updated actor representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [actor]
                    properties:
                      actor:
                        $ref: "#/components/schemas/Actor"
        "401":
          $ref: "#/components/responses/Error"
  /actors/self/avatar/content:
    get:
      tags:
        - Actors
      summary: Get the authenticated actor avatar content
      operationId: getActorAvatarContent
      description: Returns the binary avatar media content for the bearer-authenticated actor.
      responses:
        "200":
          description: Avatar media content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Error"
  /contacts/{contact_ref}/avatar:
    put:
      tags:
        - Contacts
      summary: Replace a contact avatar
      operationId: replaceContactAvatar
      description: Stores avatar media for a canonical contact identified by contact reference.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvatarUpload"
      responses:
        "200":
          description: Updated contact representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [contact]
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Contacts
      summary: Delete a contact avatar
      operationId: deleteContactAvatar
      description: Deletes avatar media for a canonical contact identified by contact reference.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      responses:
        "200":
          description: Updated contact representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [contact]
                    properties:
                      contact:
                        $ref: "#/components/schemas/Contact"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /contacts/{contact_ref}/avatar/content:
    get:
      tags:
        - Contacts
      summary: Get contact avatar content
      operationId: getContactAvatarContent
      description: Returns the binary avatar media content for a canonical contact identified by contact reference.
      parameters:
        - $ref: "#/components/parameters/ContactRef"
      responses:
        "200":
          description: Avatar media content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /agreements/imports:
    post:
      tags:
        - Imports
      summary: Import an agreement
      operationId: importAgreement
      description: Creates a canonical agreement by importing a canonical document payload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CanonicalDocument"
      responses:
        "201":
          description: Agreement created from import.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [agreement]
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /templates/imports:
    post:
      tags:
        - Imports
      summary: Import a template
      operationId: importTemplate
      description: Creates a canonical template by importing a canonical document payload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CanonicalDocument"
      responses:
        "201":
          description: Template created from import.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [template]
                    properties:
                      template:
                        $ref: "#/components/schemas/Template"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/attachments:
    get:
      tags:
        - Attachments
      summary: List agreement attachments
      operationId: listAgreementAttachments
      description: Returns canonical attachments scoped to the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "200":
          description: Agreement attachment list.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachments]
                    properties:
                      attachments:
                        type: array
                        items:
                          $ref: "#/components/schemas/Attachment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Attachments
      summary: Create an agreement attachment
      operationId: createAgreementAttachment
      description: Creates a canonical attachment scoped to the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttachmentCreate"
      responses:
        "201":
          description: Attachment created.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachment]
                    properties:
                      attachment:
                        $ref: "#/components/schemas/Attachment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/attachments:
    get:
      tags:
        - Attachments
      summary: List template attachments
      operationId: listTemplateAttachments
      description: Returns canonical attachments scoped to the identified template.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "200":
          description: Template attachment list.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachments]
                    properties:
                      attachments:
                        type: array
                        items:
                          $ref: "#/components/schemas/Attachment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags:
        - Attachments
      summary: Create a template attachment
      operationId: createTemplateAttachment
      description: Creates a canonical attachment scoped to the identified template.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttachmentCreate"
      responses:
        "201":
          description: Attachment created.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachment]
                    properties:
                      attachment:
                        $ref: "#/components/schemas/Attachment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /attachments/{attachment_ref}:
    put:
      tags:
        - Attachments
      summary: Update an attachment
      operationId: updateAttachment
      description: Updates canonical attachment metadata identified by attachment reference.
      parameters:
        - $ref: "#/components/parameters/AttachmentRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttachmentUpdate"
      responses:
        "200":
          description: Updated attachment representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachment]
                    properties:
                      attachment:
                        $ref: "#/components/schemas/Attachment"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
    delete:
      tags:
        - Attachments
      summary: Delete an attachment
      operationId: deleteAttachment
      description: Deletes canonical attachment metadata and returns its final representation.
      parameters:
        - $ref: "#/components/parameters/AttachmentRef"
      responses:
        "200":
          description: Deleted attachment representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [attachment]
                    properties:
                      attachment:
                        $ref: "#/components/schemas/Attachment"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /templates/{template_ref}/content:
    get:
      tags:
        - Templates
      summary: Get template content
      operationId: getTemplateContent
      description: Returns the canonical document content compiled from the identified template.
      parameters:
        - $ref: "#/components/parameters/TemplateRef"
      responses:
        "200":
          description: Canonical template content.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [content]
                    properties:
                      content:
                        $ref: "#/components/schemas/CanonicalDocument"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/protocols:
    get:
      tags:
        - Signing
      summary: Get agreement signing protocol
      operationId: getAgreementProtocol
      description: Returns the current signing state and the single valid next action for the identified agreement.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "200":
          description: Agreement signing protocol state.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: "#/components/schemas/Protocol"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /protocols/{agreement_ref}/authentications:
    post:
      tags:
        - Signing
      summary: Create a protocol authentication
      operationId: createProtocolAuthentication
      description: Creates the current signing authentication transition for the identified agreement protocol.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthenticationCreate"
      responses:
        "200":
          description: Session continuation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "201":
          description: Refreshed authenticated session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "202":
          description: Verification challenge for authentication completion.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResponse"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /protocols/{agreement_ref}/rcp/assignments:
    post:
      tags:
        - Signing
      summary: Create an RCP assignment
      operationId: createProtocolRcpAssignment
      description: Creates the reciprocal confirmation requirements for the identified agreement protocol.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      responses:
        "200":
          description: Updated reciprocal confirmation context.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [rcp]
                    properties:
                      rcp:
                        $ref: "#/components/schemas/RcpContext"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
  /protocols/{agreement_ref}/rcp/confirmations:
    post:
      tags:
        - Signing
      summary: Create an RCP confirmation
      operationId: createProtocolRcpConfirmation
      description: Confirms the current reciprocal confirmation challenge for the identified agreement protocol.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RcpConfirmation"
      responses:
        "200":
          description: Updated reciprocal confirmation state.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [challenge, rcp]
                    properties:
                      challenge:
                        $ref: "#/components/schemas/RcpChallenge"
                      rcp:
                        $ref: "#/components/schemas/RcpContext"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /agreements/{agreement_ref}/signatures:
    post:
      tags:
        - Signing
      summary: Create a signature
      operationId: createAgreementSignature
      description: Attempts to create the actor's agreement signature and returns either the created signature or a verification challenge.
      parameters:
        - $ref: "#/components/parameters/AgreementRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignatureCreate"
            examples:
              example:
                summary: Sign an agreement
                value:
                  legal_affirmed: true
      responses:
        "200":
          description: Agreement signing result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureCreateResponse"
        "201":
          description: Agreement signing result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureCreateResponse"
              examples:
                example:
                  summary: Signature created
                  value:
                    data:
                      agreement:
                        ref: "a1b2c3d4-0001-4000-8000-000000000001"
                        name: "PRD: Enterprise Data Export v1"
                        status: signing
                        intent: binding
                        priority: high
                        executed_at: null
                        rejected_at: null
                        rejected_reason: null
                        requires_2fa: false
                        requires_rcp: false
                        description: null
                        sections: []
                        terms: []
                      signature:
                        ref: "a1b2c3d4-0701-4000-8000-000000000001"
                        created_at: "2026-06-27T14:00:00Z"
                        requires_2fa: false
                      verification: null
        "202":
          description: Agreement signing result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignatureCreateResponse"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
  /verifications/{verification_ref}/confirmations:
    post:
      tags:
        - Signing
      summary: Create a verification confirmation
      operationId: createVerificationConfirmation
      description: Completes the current signing-related verification challenge identified by verification reference.
      parameters:
        - $ref: "#/components/parameters/VerificationRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerificationCode"
      responses:
        "201":
          description: Refreshed authenticated session.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [session]
                    properties:
                      session:
                        $ref: "#/components/schemas/Session"
        "202":
          description: Updated agreement representation.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [agreement]
                    properties:
                      agreement:
                        $ref: "#/components/schemas/Agreement"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "422":
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Bearer
  parameters:
    AttachmentRef:
      name: attachment_ref
      in: path
      required: true
      description: Public attachment reference.
      schema:
        $ref: "#/components/schemas/Ref"
    AgreementRef:
      name: agreement_ref
      in: path
      required: true
      description: Public agreement reference.
      schema:
        $ref: "#/components/schemas/Ref"
    CommentRef:
      name: comment_ref
      in: path
      required: true
      description: Public comment reference.
      schema:
        $ref: "#/components/schemas/Ref"
    ContactRef:
      name: contact_ref
      in: path
      required: true
      description: Public contact reference.
      schema:
        $ref: "#/components/schemas/Ref"
    InvitationRef:
      name: invitation_ref
      in: path
      required: true
      description: Public invitation reference.
      schema:
        $ref: "#/components/schemas/Ref"
    ParticipantRef:
      name: participant_ref
      in: path
      required: true
      description: Public participant reference.
      schema:
        $ref: "#/components/schemas/Ref"
    SectionRef:
      name: section_ref
      in: path
      required: true
      description: Public section reference.
      schema:
        $ref: "#/components/schemas/Ref"
    TemplateRef:
      name: template_ref
      in: path
      required: true
      description: Public template reference.
      schema:
        $ref: "#/components/schemas/Ref"
    TermRef:
      name: term_ref
      in: path
      required: true
      description: Public term reference.
      schema:
        $ref: "#/components/schemas/Ref"
    VerificationRef:
      name: verification_ref
      in: path
      required: true
      description: Public verification reference.
      schema:
        $ref: "#/components/schemas/Ref"
    Page:
      name: page
      in: query
      required: false
      description: One-based page number.
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: page_size
      in: query
      required: false
      description: Maximum number of records returned per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    Error:
      description: Standard API error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Ref:
      type: string
      format: uuid
      description: Public stable resource reference.
    Actor:
      type: object
      description: Canonical actor identity summary for bearer authentication.
      required:
        - avatar_url
        - email
        - family_name
        - given_name
        - job_title
        - kind
        - name
        - organization
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        email:
          type:
            - string
            - "null"
          format: email
        family_name:
          type:
            - string
            - "null"
        given_name:
          type:
            - string
            - "null"
        job_title:
          type:
            - string
            - "null"
        kind:
          type: string
        name:
          type: string
        organization:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
    ActorUpdate:
      type: object
      description: Authenticated actor update payload.
      additionalProperties: false
      properties:
        family_name:
          type:
            - string
            - "null"
        given_name:
          type:
            - string
            - "null"
        job_title:
          type:
            - string
            - "null"
        organization:
          type:
            - string
            - "null"
    NotificationSettings:
      type: object
      description: Notification preference flags for the authenticated actor.
      required:
        - agreement_execution
        - agreement_invitations
        - comments_mentions
        - signature_requests
        - term_revisions
        - weekly_digest
      properties:
        agreement_execution:
          type: boolean
        agreement_invitations:
          type: boolean
        comments_mentions:
          type: boolean
        signature_requests:
          type: boolean
        term_revisions:
          type: boolean
        weekly_digest:
          type: boolean
    NotificationSettingsUpdate:
      type: object
      description: Notification preference update payload for the authenticated actor.
      additionalProperties: false
      properties:
        agreement_execution:
          type: boolean
        agreement_invitations:
          type: boolean
        comments_mentions:
          type: boolean
        signature_requests:
          type: boolean
        term_revisions:
          type: boolean
        weekly_digest:
          type: boolean
    SecuritySettings:
      type: object
      description: Security context for the authenticated actor.
      additionalProperties: true
    Settings:
      type: object
      description: Settings view for the authenticated actor.
      required:
        - notifications
        - security
      properties:
        notifications:
          $ref: "#/components/schemas/NotificationSettings"
        security:
          $ref: "#/components/schemas/SecuritySettings"
    AvatarUpload:
      type: object
      description: Base64-encoded avatar upload payload.
      additionalProperties: false
      required:
        - content_base64
        - content_type
      properties:
        content_base64:
          type: string
        content_type:
          type: string
    Contact:
      type: object
      description: Canonical contact resource.
      required:
        - avatar_url
        - email
        - family_name
        - given_name
        - name
        - notes
        - organization
        - phone
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        email:
          type: string
          format: email
        family_name:
          type:
            - string
            - "null"
        given_name:
          type: string
        name:
          type: string
        notes:
          type:
            - string
            - "null"
        organization:
          type:
            - string
            - "null"
        phone:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
    CommentActor:
      type: object
      description: Actor identity attached to a comment.
      required:
        - avatar_url
        - name
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    CommentRevision:
      type: object
      description: Revision reference attached to a comment.
      required:
        - latest
        - ref
      properties:
        latest:
          type: boolean
        ref:
          type:
            - string
            - "null"
          format: uuid
    CommentResourceRef:
      type: object
      description: Nested resource reference attached to a comment.
      required:
        - ref
      properties:
        ref:
          type:
            - string
            - "null"
          format: uuid
    Comment:
      type: object
      description: Canonical comment resource.
      required:
        - actor
        - content
        - created_at
        - on_revision
        - ref
        - revision
        - section
        - term
      properties:
        actor:
          $ref: "#/components/schemas/CommentActor"
        content:
          type: string
        created_at:
          type: string
          format: date-time
        on_revision:
          type: boolean
        ref:
          $ref: "#/components/schemas/Ref"
        revision:
          anyOf:
            - $ref: "#/components/schemas/CommentRevision"
            - type: "null"
        section:
          anyOf:
            - $ref: "#/components/schemas/CommentResourceRef"
            - type: "null"
        term:
          anyOf:
            - $ref: "#/components/schemas/CommentResourceRef"
            - type: "null"
    AgreementPartial:
      type: object
      description: Canonical agreement summary.
      required:
        - description
        - intent
        - name
        - ref
        - status
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        status:
          type: string
    Section:
      type: object
      description: Canonical section resource.
      required:
        - description
        - name
        - position
        - ref
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        position:
          type:
            - integer
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    Term:
      type: object
      description: Canonical term resource.
      required:
        - description
        - has_review_history
        - locked
        - name
        - negotiable
        - pending_counter_proposal
        - position
        - priority
        - ref
      properties:
        description:
          type:
            - string
            - "null"
        has_review_history:
          type: boolean
        locked:
          type: boolean
        name:
          type: string
        negotiable:
          type: boolean
        pending_counter_proposal:
          type: boolean
        position:
          type:
            - integer
            - "null"
        priority:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
    Agreement:
      type: object
      description: Canonical agreement resource.
      required:
        - description
        - executed_at
        - intent
        - name
        - priority
        - rejected_at
        - rejected_reason
        - ref
        - requires_2fa
        - requires_rcp
        - sections
        - status
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        executed_at:
          type:
            - string
            - "null"
          format: date-time
        intent:
          type: string
        name:
          type: string
        priority:
          type: string
        rejected_at:
          type:
            - string
            - "null"
          format: date-time
        rejected_reason:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
        requires_rcp:
          type: boolean
        sections:
          type: array
          items:
            $ref: "#/components/schemas/Section"
        status:
          type: string
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    AgreementCreate:
      type: object
      description: Agreement creation payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
          enum: [binding, nonbinding]
        name:
          type: string
        priority:
          type: string
          enum: [low, medium, high, urgent]
        requires_2fa:
          type: integer
          enum: [0, 1]
        requires_rcp:
          type: integer
          enum: [0, 1]
    AgreementUpdate:
      type: object
      description: Agreement update payload.
      additionalProperties: false
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
          enum: [binding, nonbinding]
        name:
          type: string
        priority:
          type: string
          enum: [low, medium, high, urgent]
        requires_2fa:
          type: integer
          enum: [0, 1]
        requires_rcp:
          type: integer
          enum: [0, 1]
    AgreementTermination:
      type: object
      description: Agreement rejection or cancellation payload.
      additionalProperties: false
      properties:
        remarks:
          type:
            - string
            - "null"
          description: Optional human-readable remarks attached to the lifecycle event.
    SectionCreate:
      type: object
      description: Section creation payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        position:
          type:
            - integer
            - "null"
    SectionReference:
      type: object
      description: Nested section reference.
      required:
        - ref
      properties:
        ref:
          $ref: "#/components/schemas/Ref"
    PlacementCreate:
      type: object
      description: Placement instruction payload.
      additionalProperties: false
      properties:
        after_ref:
          type:
            - string
            - "null"
        before_ref:
          type:
            - string
            - "null"
        direction:
          type:
            - string
            - "null"
          enum: [up, down, null]
        target_root:
          type:
            - boolean
            - "null"
        target_section_ref:
          type:
            - string
            - "null"
    TermConditionChange:
      type: object
      description: Term condition payload.
      additionalProperties: false
      required:
        - negotiable
      properties:
        negotiable:
          type: integer
          enum: [0, 1]
    SectionUpdate:
      type: object
      description: Section update payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        position:
          type:
            - integer
            - "null"
    TermCreate:
      type: object
      description: Term creation payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        negotiable:
          type:
            - integer
            - "null"
          enum: [0, 1, null]
        position:
          type:
            - integer
            - "null"
        priority:
          type: string
          enum: [low, medium, high, urgent]
        section:
          anyOf:
            - $ref: "#/components/schemas/SectionReference"
            - type: "null"
    TermUpdate:
      type: object
      description: Term update payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        negotiable:
          type:
            - integer
            - "null"
          enum: [0, 1, null]
        position:
          type:
            - integer
            - "null"
        priority:
          type: string
          enum: [low, medium, high, urgent]
    CommentCreate:
      type: object
      description: Comment creation payload.
      additionalProperties: false
      required:
        - content
      properties:
        content:
          type: string
        on_revision:
          type: boolean
    CommentUpdate:
      type: object
      description: Comment update payload.
      additionalProperties: false
      required:
        - content
      properties:
        content:
          type: string
        on_revision:
          type: boolean
    DecisionActor:
      type: object
      description: Actor identity attached to a decision.
      required:
        - avatar_url
        - name
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    DecisionRevision:
      type: object
      description: Revision reference attached to a decision.
      required:
        - ref
      properties:
        ref:
          $ref: "#/components/schemas/Ref"
    Decision:
      type: object
      description: Canonical decision resource.
      required:
        - actor
        - created_at
        - ref
        - remarks
        - revision
        - status
      properties:
        actor:
          anyOf:
            - $ref: "#/components/schemas/DecisionActor"
            - type: "null"
        created_at:
          type: string
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
        remarks:
          type:
            - string
            - "null"
        revision:
          anyOf:
            - $ref: "#/components/schemas/DecisionRevision"
            - type: "null"
        status:
          type: string
          enum: [accepted, rejected]
    DecisionCreate:
      type: object
      description: Decision creation payload.
      additionalProperties: false
      required:
        - status
      properties:
        proposed_description:
          type:
            - string
            - "null"
        proposed_name:
          type:
            - string
            - "null"
        remarks:
          type:
            - string
            - "null"
        status:
          type: string
          enum: [accepted, rejected]
        supersedes_decision_ref:
          type:
            - string
            - "null"
    RevisionActor:
      type: object
      description: Actor identity attached to a revision.
      required:
        - name
        - ref
      properties:
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    Revision:
      type: object
      description: Canonical revision resource.
      required:
        - actor
        - created_at
        - decisions
        - description
        - latest
        - name
        - number
        - ref
      properties:
        actor:
          anyOf:
            - $ref: "#/components/schemas/RevisionActor"
            - type: "null"
        created_at:
          type: string
          format: date-time
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        description:
          type:
            - string
            - "null"
        latest:
          type: boolean
        name:
          type:
            - string
            - "null"
        number:
          type: integer
        ref:
          $ref: "#/components/schemas/Ref"
    RevisionProposal:
      type: object
      description: Revision proposal payload.
      additionalProperties: false
      required:
        - description
      properties:
        description:
          type: string
        name:
          type:
            - string
            - "null"
        remarks:
          type:
            - string
            - "null"
    TemplatePartial:
      type: object
      description: Canonical template partial.
      required:
        - description
        - intent
        - name
        - ref
        - status
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        status:
          type: string
    Template:
      type: object
      description: Canonical template resource.
      required:
        - description
        - executed_at
        - intent
        - name
        - priority
        - rejected_at
        - rejected_reason
        - ref
        - requires_2fa
        - requires_rcp
        - sections
        - status
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        executed_at:
          type:
            - string
            - "null"
          format: date-time
        intent:
          type: string
        name:
          type: string
        priority:
          type: string
        rejected_at:
          type:
            - string
            - "null"
          format: date-time
        rejected_reason:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
        requires_rcp:
          type: boolean
        sections:
          type: array
          items:
            $ref: "#/components/schemas/Section"
        status:
          type: string
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    TemplateCreate:
      type: object
      description: Template creation payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
          enum: [binding, nonbinding]
        name:
          type: string
        priority:
          type: string
          enum: [low, medium, high, urgent]
        requires_2fa:
          type: integer
          enum: [0, 1]
        requires_rcp:
          type: integer
          enum: [0, 1]
    TemplateUpdate:
      type: object
      description: Template update payload.
      additionalProperties: false
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
          enum: [binding, nonbinding]
        name:
          type: string
        priority:
          type: string
          enum: [low, medium, high, urgent]
        requires_2fa:
          type: integer
          enum: [0, 1]
        requires_rcp:
          type: integer
          enum: [0, 1]
    ContactCreate:
      type: object
      description: Contact creation payload.
      additionalProperties: false
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        notes:
          type:
            - string
            - "null"
        organization:
          type:
            - string
            - "null"
        phone:
          type:
            - string
            - "null"
    ContactUpdate:
      type: object
      description: Contact update payload.
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        notes:
          type:
            - string
            - "null"
        organization:
          type:
            - string
            - "null"
        phone:
          type:
            - string
            - "null"
    Attachment:
      type: object
      description: Canonical attachment resource.
      required:
        - checksum
        - checksum_algorithm
        - description
        - kind
        - name
        - ref
        - url
      properties:
        checksum:
          type:
            - string
            - "null"
        checksum_algorithm:
          type:
            - string
            - "null"
        description:
          type:
            - string
            - "null"
        kind:
          type: string
          enum: [file, url]
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        url:
          type:
            - string
            - "null"
    AttachmentCreate:
      type: object
      description: Attachment creation payload.
      additionalProperties: false
      required:
        - name
      properties:
        content_base64:
          type:
            - string
            - "null"
        description:
          type:
            - string
            - "null"
        kind:
          type: string
          enum: [file, url]
        name:
          type: string
        url:
          type:
            - string
            - "null"
    AttachmentUpdate:
      type: object
      description: Attachment update payload.
      additionalProperties: false
      required:
        - name
      properties:
        description:
          type:
            - string
            - "null"
        kind:
          type: string
          enum: [file, url]
        name:
          type: string
        url:
          type:
            - string
            - "null"
    CanonicalDocument:
      type: object
      description: Canonical agreement or template document payload.
      additionalProperties: true
    Session:
      type: object
      description: Authenticated session continuation payload.
      additionalProperties: true
    ProtocolState:
      type: object
      description: Current server-driven signing protocol state for the authenticated actor.
      enum:
        - idle
        - authenticate
        - confirm_authentication
        - assign_rcp
        - confirm_rcp
        - verify_signature
        - sign
    JsonSchema:
      type: object
      description: Inline JSON Schema document that validates the next action request body.
      additionalProperties: true
    ProtocolAction:
      type: object
      description: Single next action exposed by the signing protocol.
      required:
        - description
        - method
        - name
        - schema
        - url
      properties:
        description:
          type: string
        method:
          type: string
          enum:
            - POST
        name:
          type: string
          enum:
            - create_authentication
            - create_rcp_assignment
            - create_rcp_confirmation
            - create_signature
            - create_verification_confirmation
        schema:
          $ref: "#/components/schemas/JsonSchema"
        url:
          type: string
    Protocol:
      type: object
      description: Current protocol state and next action for agreement signing.
      required:
        - action
        - state
      properties:
        state:
          $ref: "#/components/schemas/ProtocolState"
        action:
          anyOf:
            - $ref: "#/components/schemas/ProtocolAction"
            - type: "null"
    SignatureVerification:
      type: object
      description: Signature or signing authentication verification challenge.
      required:
        - channel
        - expires_at
        - ref
      properties:
        channel:
          type:
            - string
            - "null"
        expires_at:
          type:
            - string
            - "null"
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
    Signature:
      type: object
      description: Canonical agreement signature record.
      required:
        - created_at
        - ref
        - requires_2fa
      properties:
        created_at:
          type: string
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
    AuthenticationCreate:
      type: object
      description: Signing authentication payload.
      additionalProperties: false
      properties:
        password:
          type:
            - string
            - "null"
    AuthenticationResponse:
      type: object
      description: Signing authentication result payload.
      required:
        - data
      properties:
        data:
          type: object
          properties:
            session:
              $ref: "#/components/schemas/Session"
            verification:
              $ref: "#/components/schemas/SignatureVerification"
    VerificationCode:
      type: object
      description: Verification code payload.
      additionalProperties: false
      required:
        - code
      properties:
        code:
          type: string
    SignatureCreate:
      type: object
      description: Signature creation payload.
      additionalProperties: false
      properties:
        legal_affirmed:
          type: boolean
    SignatureCreateResponse:
      type: object
      description: Signature creation result payload.
      required:
        - data
      properties:
        data:
          type: object
          required:
            - agreement
          properties:
            agreement:
              $ref: "#/components/schemas/Agreement"
            signature:
              $ref: "#/components/schemas/Signature"
            verification:
              $ref: "#/components/schemas/SignatureVerification"
    RcpExpectedActor:
      type: object
      description: Actor identity attached to a remote confirmation requirement.
      required:
        - name
        - ref
      properties:
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    RcpIncomingRequirement:
      type: object
      description: Incoming remote confirmation requirement for the authenticated actor.
      required:
        - confirmed_at
        - expected_from
        - token
      properties:
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        expected_from:
          anyOf:
            - $ref: "#/components/schemas/RcpExpectedActor"
            - type: "null"
        token:
          type: string
    RcpOutgoingAssignment:
      type: object
      description: Outgoing remote confirmation assignment issued by the authenticated actor.
      required:
        - code
        - confirmed_at
        - recipient
        - token
      properties:
        code:
          type: string
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        recipient:
          anyOf:
            - $ref: "#/components/schemas/RcpExpectedActor"
            - type: "null"
        token:
          type: string
    RcpContext:
      type: object
      description: Remote confirmation party context for an agreement.
      required:
        - completed_count
        - incoming_requirement
        - outgoing_assignment
        - ready
        - total_count
      properties:
        completed_count:
          type: integer
        incoming_requirement:
          anyOf:
            - $ref: "#/components/schemas/RcpIncomingRequirement"
            - type: "null"
        outgoing_assignment:
          anyOf:
            - $ref: "#/components/schemas/RcpOutgoingAssignment"
            - type: "null"
        ready:
          type: boolean
        total_count:
          type: integer
    RcpChallenge:
      type: object
      description: Remote confirmation challenge state.
      required:
        - code
        - confirmed_at
        - ref
      properties:
        code:
          type: string
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
    RcpConfirmation:
      type: object
      description: Remote confirmation completion payload.
      additionalProperties: false
      required:
        - attested
        - code
        - token
      properties:
        attested:
          type: boolean
        code:
          type: string
        token:
          type: string
    ParticipantActor:
      type: object
      description: Linked actor identity for an active participant.
      required:
        - ref
      properties:
        kind:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
    Participant:
      type: object
      description: Canonical agreement participant resource.
      required:
        - active
        - actor
        - avatar_url
        - email
        - name
        - ref
        - type
      properties:
        active:
          type: boolean
        actor:
          anyOf:
            - $ref: "#/components/schemas/ParticipantActor"
            - type: "null"
        avatar_url:
          type:
            - string
            - "null"
        email:
          type: string
          format: email
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    InvitationPartial:
      type: object
      description: Partial invitation resource returned when participant creation requires recipient acceptance.
      required:
        - email
        - ref
        - type
      properties:
        email:
          type: string
          format: email
        ref:
          $ref: "#/components/schemas/Ref"
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    InvitationReference:
      type: object
      description: Invitation reference returned by invitation lifecycle events.
      required:
        - ref
      properties:
        ref:
          $ref: "#/components/schemas/Ref"
    ParticipantCreate:
      type: object
      description: Participant creation payload.
      additionalProperties: false
      required:
        - email
        - name
        - type
      properties:
        agent_ref:
          anyOf:
            - $ref: "#/components/schemas/Ref"
            - type: "null"
        email:
          type: string
          format: email
        name:
          type: string
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    ParticipantUpdate:
      type: object
      description: Participant update payload.
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    ParticipantSelfJoinCreate:
      type: object
      description: Participant self-join payload.
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [editor, signer]
    Pagination:
      type: object
      description: Standard paginated collection metadata.
      required:
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
    Error:
      type: object
      description: Standard API error envelope.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
            - status
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            status:
              type: integer
            fields:
              type: array
              items:
                type: object
                additionalProperties: true
