AI Demos Page Drafts API

openapi: 3.2.0
info:
  title: Aidemos Com Page Drafts API
  version: 0.1.0
  description: 'Operations tagged page-drafts across 2 of this provider''s published API definitions: aidemos-com-openapi.json, mcp-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: page-drafts
paths:
  /v1/page-drafts:
    get:
      tags:
      - page-drafts
      summary: List Page Drafts
      description: List the canonical drafts a run produced (summaries). Payload fetches each by id to land.
      operationId: list_page_drafts_v1_page_drafts_get
      parameters:
      - name: run_id
        in: query
        required: true
        schema:
          type: string
          description: ai_job_runs.request_id (the GET /v1/jobs run id)
          title: Run Id
        description: ai_job_runs.request_id (the GET /v1/jobs run id)
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PageDraftSummary'
                title: Response List Page Drafts V1 Page Drafts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/page-drafts/recent:
    get:
      tags:
      - page-drafts
      summary: List Recent Page Drafts
      description: 'Recent canonical drafts across EVERY run (not one run), newest first, each carrying its run''s

        title + created_at. The console loads this in ONE call so Generated-Drafts search spans the whole

        history — the per-run fanout only fetched the 15 newest runs, so older runs'' pages silently fell

        out of search and looked auto-removed (ClickUp 86bauyt8q; the drafts were never actually deleted).'
      operationId: list_recent_page_drafts_v1_page_drafts_recent_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          description: most-recent N drafts across ALL runs (search spans everything)
          default: 500
          title: Limit
        description: most-recent N drafts across ALL runs (search spans everything)
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/page-drafts/{draft_id}:
    get:
      tags:
      - page-drafts
      summary: Get Page Draft
      description: 'One canonical draft — the draft payload + landing manifest + regression. This is what

        Payload lands (instead of the job-result draft) so Python is the origin of record.'
      operationId: get_page_draft_v1_page_drafts__draft_id__get
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDraft'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/sync/page/{draft_id}:
    post:
      tags:
      - page-drafts
      summary: Sync Page
      description: 'Payload reports the record it landed this draft into. Python records the back-reference and

        marks the draft landed/published — making Python the origin while Payload holds the reference.'
      operationId: sync_page_v1_sync_page__draft_id__post
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/app__api__page_drafts__SyncRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDraftSummary'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/diff/page/{draft_id}:
    post:
      tags:
      - page-drafts
      summary: Diff Page
      description: 'Compare Payload''s current value against the frozen generated_snapshot. A non-empty diff means

        the landed page was edited since generation — a re-generation must NOT silently overwrite it.'
      operationId: diff_page_v1_diff_page__draft_id__post
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiffRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiffResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/page-drafts/{draft_id}/edit:
    get:
      tags:
      - page-drafts
      summary: Get Page Draft Edit
      description: 'Editor read for a DRAFT: {canonical, override, effective, meta, live_summary, review_flags}.

        `live_summary` carries the published page''s status + feature count so the editor can show

        ''Live: N · Draft: M''; `review_flags` is the same reconciliation the publish gate refuses on

        (#370), so the panel never asks an operator to resolve a flag the gate already ignores.'
      operationId: get_page_draft_edit_v1_page_drafts__draft_id__edit_get
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Page Draft Edit V1 Page Drafts  Draft Id  Edit Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/page-drafts/{draft_id}/override:
    put:
      tags:
      - page-drafts
      summary: Put Page Draft Override
      description: 'Save the human override layer ONTO THE DRAFT (replaces the stored draft override). The pristine

        merged canonical_payload is untouched — a later re-generation re-merges the union without losing

        these edits. Returns the new draft layers. No cache bust: a draft is not in the public read set.'
      operationId: put_page_draft_override_v1_page_drafts__draft_id__override_put
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DraftOverridePut'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Put Page Draft Override V1 Page Drafts  Draft Id  Override Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/page-drafts/{draft_id}/publish:
    post:
      tags:
      - page-drafts
      summary: Publish Page Draft
      description: 'Publish the merged DRAFT → make it the live page (#98). Applies the draft''s LAYERS onto

        sip.page_content for (page_type, slug): canonical = the pristine merge, override = the draft''s human

        edits — preserving the canonical/override split so a future regen re-merges into canonical without

        dropping the edits (the same invariant page_content guarantees). Runs the SAME SEO + CONFLICT gates

        as the page-content publish, flips the live row to published, busts the site cache, and marks the

        draft published so it stops surfacing as a pending working copy. This OVERWRITES the live published

        page — the caller (editor) gates it behind a confirm dialog.'
      operationId: publish_page_draft_v1_page_drafts__draft_id__publish_post
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: force
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Force
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Publish Page Draft V1 Page Drafts  Draft Id  Publish Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PageDraftSummary:
      properties:
        id:
          type: string
          title: Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        page_type:
          type: string
          title: Page Type
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        source_node_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Node Id
        status:
          type: string
          title: Status
        payload_collection:
          anyOf:
          - type: string
          - type: 'null'
          title: Payload Collection
        payload_record_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payload Record Id
        has_regression:
          type: boolean
          title: Has Regression
          default: false
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - page_type
      - status
      title: PageDraftSummary
    DiffRequest:
      properties:
        current_value:
          additionalProperties: true
          type: object
          title: Current Value
          description: Payload's current value for this page; diffed vs the frozen snapshot
      type: object
      required:
      - current_value
      title: DiffRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DraftOverridePut:
      properties:
        override:
          additionalProperties: true
          type: object
          title: Override
      type: object
      required:
      - override
      title: DraftOverridePut
    app__api__page_drafts__SyncRequest:
      properties:
        collection:
          type: string
          title: Collection
          description: Payload collection the draft was landed into
        record_id:
          type: string
          title: Record Id
          description: Payload record id (stringified)
        status:
          type: string
          title: Status
          description: landed | published-mirror
          default: landed
      type: object
      required:
      - collection
      - record_id
      title: SyncRequest
    PageDraft:
      properties:
        id:
          type: string
          title: Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        page_type:
          type: string
          title: Page Type
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        source_node_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Node Id
        status:
          type: string
          title: Status
        payload_collection:
          anyOf:
          - type: string
          - type: 'null'
          title: Payload Collection
        payload_record_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payload Record Id
        has_regression:
          type: boolean
          title: Has Regression
          default: false
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        canonical_payload:
          additionalProperties: true
          type: object
          title: Canonical Payload
        manifest:
          anyOf:
          - {}
          - type: 'null'
          title: Manifest
        regression:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Regression
        landed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Landed At
      type: object
      required:
      - id
      - page_type
      - status
      - canonical_payload
      title: PageDraft
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DiffResponse:
      properties:
        id:
          type: string
          title: Id
        edited:
          type: boolean
          title: Edited
          description: True if current_value diverges from generated_snapshot
        added:
          items:
            type: string
          type: array
          title: Added
          default: []
        missing:
          items:
            type: string
          type: array
          title: Missing
          default: []
        changed:
          items:
            type: string
          type: array
          title: Changed
          default: []
      type: object
      required:
      - id
      - edited
      title: DiffResponse
x-refined-from:
- aidemos-com-openapi.json
- mcp-openapi.json