repowise-dev Pages API

openapi: 3.2.0
info:
  title: repowise Pages API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: Pages
paths:
  /api/pages:
    get:
      tags:
      - Pages
      summary: List Pages
      description: List wiki pages for a repository.
      operationId: list_pages_api_pages_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: query
        required: true
        schema:
          type: string
          description: Repository ID
          title: Repo Id
        description: Repository ID
      - name: page_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by page type
          title: Page Type
        description: Filter by page type
      - name: has_prose
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: 'Scoped to the model-written page types (the concept tree and onboarding): true = only the ones a model has written, false = only the ones still stubs; omit for every page of every type.'
          title: Has Prose
        description: 'Scoped to the model-written page types (the concept tree and onboarding): true = only the ones a model has written, false = only the ones still stubs; omit for every page of every type.'
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          description: 'Sort field: updated_at, confidence, created_at'
          default: updated_at
          title: Sort By
        description: 'Sort field: updated_at, confidence, created_at'
      - name: order
        in: query
        required: false
        schema:
          type: string
          description: 'Sort order: asc or desc'
          default: desc
          title: Order
        description: 'Sort order: asc or desc'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: fields
        in: query
        required: false
        schema:
          type: string
          description: How much of each page to return. 'full' (the default) is every field. 'summary' drops 'content' and 'metadata' — together 95% of a listing's bytes, and read by nothing that renders a list of pages — and adds 'content_chars' in their place.
          default: full
          title: Fields
        description: How much of each page to return. 'full' (the default) is every field. 'summary' drops 'content' and 'metadata' — together 95% of a listing's bytes, and read by nothing that renders a list of pages — and adds 'content_chars' in their place.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/pages/lookup:
    get:
      tags:
      - Pages
      summary: Get Page By Query
      description: 'Get a single wiki page by ID passed as query parameter.


        Use this endpoint when the page_id contains characters that are

        difficult to encode in a URL path.


        ``repo_id`` is what routes the session to the right database. Without it a

        workspace server looks the page up in whichever store is the default, and a

        page id that exists in another repo comes back as a 404 — so any caller

        that knows the repo should say so.


        A retired page id resolves to whatever took over from it; the response then

        carries ``X-Repowise-Redirected-From``.'
      operationId: get_page_by_query_api_pages_lookup_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: page_id
        in: query
        required: true
        schema:
          type: string
          description: Page ID (e.g. file_page:src/main.py)
          title: Page Id
        description: Page ID (e.g. file_page:src/main.py)
      - name: repo_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Repository the page belongs to. Optional, but required to reach a page outside the default store in workspace mode, where the session is routed by this value.
          title: Repo Id
        description: Repository the page belongs to. Optional, but required to reach a page outside the default store in workspace mode, where the session is routed by this value.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/pages/lookup/versions:
    get:
      tags:
      - Pages
      summary: Get Page Versions By Query
      description: Get version history for a wiki page (page_id as query param).
      operationId: get_page_versions_by_query_api_pages_lookup_versions_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: page_id
        in: query
        required: true
        schema:
          type: string
          description: Page ID
          title: Page Id
        description: Page ID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PageVersionResponse'
                title: Response Get Page Versions By Query Api Pages Lookup Versions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/pages/lookup/notes:
    patch:
      tags:
      - Pages
      summary: Update Page Notes
      description: 'Set or clear the human-curated note pinned above a page''s generated

        content. Notes survive regeneration, so this never touches versions.'
      operationId: update_page_notes_api_pages_lookup_notes_patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: page_id
        in: query
        required: true
        schema:
          type: string
          description: Page ID
          title: Page Id
        description: Page ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageNotesUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/pages/lookup/regenerate:
    post:
      tags:
      - Pages
      summary: Regenerate Page By Query
      description: 'Force-regenerate a single wiki page (page_id as query param).


        Creates a ``single_page`` generation job and launches it immediately (D1):

        the previous version created a ``pending`` row and never committed or

        launched it, so the click did nothing until a 15-minute polling fallback

        picked it up while the active-job guard blocked syncs.


        An optional ``style`` overrides the repo''s default style for this page only,

        and ``cascade`` controls whether the pages summarizing this one are refreshed

        too. Both are validated here and carried in the job config; the executor

        resolves them.'
      operationId: regenerate_page_by_query_api_pages_lookup_regenerate_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: page_id
        in: query
        required: true
        schema:
          type: string
          description: Page ID
          title: Page Id
        description: Page ID
      - name: repo_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Repository ID. Required in workspace mode to route to the correct repository database.
          title: Repo Id
        description: Repository ID. Required in workspace mode to route to the correct repository database.
      - name: style
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional wiki style to regenerate this page in (per-page override).
          title: Style
        description: Optional wiki style to regenerate this page in (per-page override).
      - name: cascade
        in: query
        required: false
        schema:
          type: string
          description: 'What to do with the pages that summarize this one: none / dependents / full.'
          default: none
          title: Cascade
        description: 'What to do with the pages that summarize this one: none / dependents / full.'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/pages/{page_id}:
    get:
      tags:
      - Pages
      summary: Get Page
      description: 'Get a single wiki page by ID in path (e.g. ``file_page:src/main.py``).


        The page_id is URL-decoded automatically by FastAPI.


        A retired page id resolves to whatever took over from it; the response then

        carries ``X-Repowise-Redirected-From``.'
      operationId: get_page_api_pages__page_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          title: Page Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    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
    JobAcceptedResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
          default: accepted
        stream_token:
          type: string
          title: Stream Token
      type: object
      required:
      - job_id
      - stream_token
      title: JobAcceptedResponse
      description: 'The 202 payload every background-job launch returns.


        ``stream_token`` authorizes ``/api/jobs/{job_id}/stream`` directly, so a

        client can attach without a second round-trip or an API key in the query

        string.'
    PageVersionResponse:
      properties:
        id:
          type: string
          title: Id
        page_id:
          type: string
          title: Page Id
        version:
          type: integer
          title: Version
        page_type:
          type: string
          title: Page Type
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
        source_hash:
          type: string
          title: Source Hash
        model_name:
          type: string
          title: Model Name
        provider_name:
          type: string
          title: Provider Name
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        confidence:
          type: number
          title: Confidence
        archived_at:
          type: string
          format: date-time
          title: Archived At
      type: object
      required:
      - id
      - page_id
      - version
      - page_type
      - title
      - content
      - source_hash
      - model_name
      - provider_name
      - input_tokens
      - output_tokens
      - confidence
      - archived_at
      title: PageVersionResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PageResponse:
      properties:
        id:
          type: string
          title: Id
        repository_id:
          type: string
          title: Repository Id
        page_type:
          type: string
          title: Page Type
        title:
          type: string
          title: Title
        target_path:
          type: string
          title: Target Path
        source_hash:
          type: string
          title: Source Hash
        model_name:
          type: string
          title: Model Name
        provider_name:
          type: string
          title: Provider Name
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        cached_tokens:
          type: integer
          title: Cached Tokens
        generation_level:
          type: integer
          title: Generation Level
        version:
          type: integer
          title: Version
        confidence:
          type: number
          title: Confidence
        freshness_status:
          type: string
          title: Freshness Status
        content_chars:
          type: integer
          title: Content Chars
        layer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Layer Id
        layer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Layer Name
        is_chapter:
          type: boolean
          title: Is Chapter
          default: false
        human_notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Human Notes
        parent_page_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Page Id
        display_order:
          type: integer
          title: Display Order
          default: 0
        section_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Section Number
        structural_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Structural Key
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        content:
          type: string
          title: Content
        digest:
          type: string
          title: Digest
          default: ''
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
      - id
      - repository_id
      - page_type
      - title
      - target_path
      - source_hash
      - model_name
      - provider_name
      - input_tokens
      - output_tokens
      - cached_tokens
      - generation_level
      - version
      - confidence
      - freshness_status
      - content_chars
      - created_at
      - updated_at
      - content
      - metadata
      title: PageResponse
    PageNotesUpdate:
      properties:
        human_notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Human Notes
      type: object
      title: PageNotesUpdate
      description: PATCH body for /lookup/notes. ``None`` clears the note.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization