openapi: 3.2.0
info:
  title: Content Documents API
  version: 1.0.0
  description: API documentation for the Content API
servers:
- url: https://api.autocontentapi.com
tags:
- name: Documents
  description: Briefing document assets generated per token
paths:
  /documents/get:
    get:
      summary: Get documents
      description: Returns paginated briefing documents created by the authenticated token, including in-progress requests.
      tags:
      - Documents
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
        description: Page number (default 1)
      - in: query
        name: pageSize
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: Items per page (default 20, max 100)
      responses:
        '200':
          description: Paginated list of documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  totalCount:
                    type: integer
                  page:
                    type: integer
                  pageSize:
                    type: integer
                  totalPages:
                    type: integer
        '401':
          description: Unauthorized
      operationId: getDocumentsGet
      x-operation-id-source: derived
  /documents/{documentId}:
    get:
      summary: Get document
      description: Returns the stored briefing document payload for the authenticated token.
      tags:
      - Documents
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: documentId
        required: true
        schema:
          type: string
        description: Document request identifier
      responses:
        '200':
          description: Document payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized
        '404':
          description: Document not found
      operationId: getDocumentsByDocumentId
      x-operation-id-source: derived
  /documents/{documentId}/download:
    get:
      summary: Download document
      description: Downloads the stored briefing document as PDF, HTML, or text for the authenticated token.
      tags:
      - Documents
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: documentId
        required: true
        schema:
          type: string
        description: Document request identifier
      responses:
        '200':
          description: Document download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: Document not found or not ready
        '502':
          description: Upstream asset unavailable
      operationId: getDocumentsByDocumentIdDownload
      x-operation-id-source: derived
  /documents/{documentId}/preview:
    get:
      summary: Preview document
      description: Streams the stored briefing document inline using its native format. Supports PDF, HTML, and plain text documents for the authenticated token.
      tags:
      - Documents
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: documentId
        required: true
        schema:
          type: string
        description: Document request identifier
      responses:
        '200':
          description: Document preview
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            text/html:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
        '404':
          description: Document not found or not ready
        '502':
          description: Upstream asset unavailable
      operationId: getDocumentsByDocumentIdPreview
      x-operation-id-source: derived
components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the document (matches request id)
        type:
          type: string
          description: Document type
        format:
          type: string
          enum:
          - text
          - html
          - pdf
          description: Stored result format
        title:
          type:
          - string
          - 'null'
          description: Optional document title
        status:
          type: integer
          description: Current progress percentage (100 when completed)
        createdOn:
          type: string
          format: date-time
          description: UTC timestamp when the document row was created
        content:
          type:
          - string
          - 'null'
          description: Text or HTML content when format is `text` or `html`
        url:
          type:
          - string
          - 'null'
          description: Direct PDF URL when format is `pdf`
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT