CoreStory Document Formatters API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Document Formatters API
  description: '# CoreStory API Overview


    The CoreStory API provides programmatic access to structured insights derived from software source code.'
  version: 1.26.2
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: document_formatters
paths:
  /api/format/available-sections/{doc_type}:
    get:
      tags:
      - document_formatters
      summary: Get available sections for a document type
      description: 'Get list of available sections for a document type.


        This helps clients know what sections they can request.'
      operationId: get_available_document_sections
      parameters:
      - name: doc_type
        in: path
        required: true
        schema:
          enum:
          - prd
          - technical-spec
          - document-section
          type: string
          description: Document type
          title: Doc Type
        description: Document type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Available Document Sections
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/table-of-contents:
    post:
      tags:
      - document_formatters
      summary: Format Table Of Contents
      description: 'Generate a table of contents for markdown content.


        Args:

        request: The request containing markdown content


        Returns:

        DocumentFormatResponse: The markdown content with table of contents'
      operationId: generate_table_of_contents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableOfContentsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFormatResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/markdown-output/{project_id}/{doc_type}:
    get:
      tags:
      - document_formatters
      summary: Retrieve and format stored document as markdown
      description: 'Retrieves a stored document (PRD, Technical Specification, or Document Section) from the database

        and formats it into a clean, readable markdown document.


        This endpoint fetches the latest PRD for the given project and formats it based on the doc_type.


        Document types:

        - prd: Full Product Requirements Document

        - technical-spec: Full Technical Specification

        - document-section: Individual document section (requires section query parameter)'
      operationId: export_document_markdown
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          description: Project ID
          title: Project Id
        description: Project ID
      - name: doc_type
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/app__models__enums__DocumentType'
          description: Document type
        description: Document type
      - name: section_name
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AllPRDStepsDashedEnum'
          - type: 'null'
          description: Section name for document-section type
          title: Section Name
        description: Section name for document-section type
      - name: show_code_references
        in: query
        required: false
        schema:
          type: boolean
          description: Include code references in user stories
          default: false
          title: Show Code References
        description: Include code references in user stories
      - name: show_references
        in: query
        required: false
        schema:
          type: boolean
          description: Include reference sections
          default: true
          title: Show References
        description: Include reference sections
      - name: generate_toc
        in: query
        required: false
        schema:
          type: boolean
          description: Generate table of contents
          default: false
          title: Generate Toc
        description: Generate table of contents
      - name: epics
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Epic IDs
          title: Epics
        description: Epic IDs
      - name: personas
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Persona IDs
          title: Personas
        description: Persona IDs
      - name: main_features
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Main feature IDs
          title: Main Features
        description: Main feature IDs
      - name: keywords
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Keyword list
          title: Keywords
        description: Keyword list
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Free-text; supports exact, "a or b", or "a and b"
          title: Search
        description: Free-text; supports exact, "a or b", or "a and b"
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Items per page (default: 999)'
          default: 999
          title: Size
        description: 'Items per page (default: 999)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFormatResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/pdf-output:
    post:
      tags:
      - document_formatters
      summary: Export document as PDF from markdown input
      description: 'Exports a document as PDF from markdown content (e.g., from artifact download).


        This endpoint accepts markdown content directly and converts it to PDF format.

        It accepts pre-formatted markdown content and converts it directly to PDF.


        The markdown should already be formatted (e.g., from a previous artifact download).


        **Plan restriction:** Requires Pro or Enterprise plan. Free users receive a

        403 error with PLAN_UPGRADE_REQUIRED.'
      operationId: export_pdf_from_markdown
      parameters:
      - name: doc_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/app__models__enums__DocumentType'
          - type: 'null'
          description: Optional document type for filename generation
          title: Doc Type
        description: Optional document type for filename generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PDFOutputRequest'
      responses:
        '200':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/document-async/{project_id}/{doc_type}:
    post:
      tags:
      - document_formatters
      summary: Initiate async PDF generation
      description: 'Initiates asynchronous PDF generation for a document.


        Returns immediately with a job_id and URLs for tracking progress:

        - stream_url: Real-time SSE updates (subscribe for progress events)

        - result_url: Download the completed PDF


        The PDF generation runs in the background via ARQ workers. Clients should:

        1. Subscribe to stream_url for real-time progress via SSE

        2. When status is ''completed'', download the PDF from result_url


        Document types:

        - prd: Full Product Requirements Document

        - technical-spec: Full Technical Specification

        - document-section: Individual document section (requires section_name query parameter)


        **Plan restriction:** Requires Pro or Enterprise plan. Free users receive a

        403 error with PLAN_UPGRADE_REQUIRED.'
      operationId: start_async_pdf_generation
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          description: Project ID
          title: Project Id
        description: Project ID
      - name: doc_type
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/app__models__enums__DocumentType'
          description: Document type
        description: Document type
      - name: section_name
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AllPRDStepsDashedEnum'
          - type: 'null'
          description: Section name for document-section type
          title: Section Name
        description: Section name for document-section type
      - name: show_code_references
        in: query
        required: false
        schema:
          type: boolean
          description: Include code references in user stories
          default: false
          title: Show Code References
        description: Include code references in user stories
      - name: show_references
        in: query
        required: false
        schema:
          type: boolean
          description: Include reference sections
          default: true
          title: Show References
        description: Include reference sections
      - name: generate_toc
        in: query
        required: false
        schema:
          type: boolean
          description: Generate table of contents
          default: false
          title: Generate Toc
        description: Generate table of contents
      - name: epics
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Epic IDs
          title: Epics
        description: Epic IDs
      - name: personas
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Persona IDs
          title: Personas
        description: Persona IDs
      - name: main_features
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: integer
          - type: 'null'
          description: Main feature IDs
          title: Main Features
        description: Main feature IDs
      - name: keywords
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Keyword list
          title: Keywords
        description: Keyword list
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Free-text; supports exact, "a or b", or "a and b"
          title: Search
        description: Free-text; supports exact, "a or b", or "a and b"
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Items per page (default: 999)'
          default: 999
          title: Size
        description: 'Items per page (default: 999)'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PDFAsyncResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/pdf-stream/{job_id}:
    get:
      tags:
      - document_formatters
      summary: Stream PDF generation progress via SSE
      description: 'Stream real-time progress updates for a PDF generation job using Server-Sent Events (SSE).


        This endpoint provides live progress updates as the PDF is being generated, without

        requiring polling. It uses Redis Pub/Sub to receive events from the ARQ worker,

        making it work seamlessly across Kubernetes pods.


        **Usage:**

        ```javascript

        const eventSource = new EventSource(''/api/format/pdf-stream/abc-123'');

        eventSource.addEventListener(''progress'', (event) => {

        const data = JSON.parse(event.data);

        console.log(`${data.progress}% - ${data.message}`);

        if (data.is_complete || data.is_error) {

        eventSource.close();

        }

        });

        ```


        The stream automatically closes when:

        - The job completes successfully (is_complete=true)

        - The job fails (is_error=true)

        - The client disconnects


        Returns:

        - 200: SSE stream of progress events

        - 403: Access denied (job belongs to different organization)

        - 404: Job not found'
      operationId: stream_pdf_generation_progress
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: The job identifier
          title: Job Id
        description: The job identifier
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/pdf-output-result/{job_id}:
    get:
      tags:
      - document_formatters
      summary: Download completed PDF
      description: 'Download the completed PDF for a finished job.


        This endpoint returns the PDF binary content with appropriate headers

        for browser download. After successful download, the PDF file is

        deleted from storage, while the SOTJ job record is retained for audit purposes.


        Clients should call this endpoint after the status endpoint returns

        ''completed'' status.


        Returns:

        - 200: PDF binary content (application/pdf)

        - 403: Access denied (job belongs to different organization)

        - 404: Job not found

        - 409: Job not yet completed (still pending/processing)

        - 410: Job failed or result no longer available


        **Authentication**: Requires user to be authenticated and have created the job.'
      operationId: download_pdf_result
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Job ID from the async initiation response
          title: Job Id
        description: Job ID from the async initiation response
      responses:
        '200':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
  /api/format/docx-output:
    post:
      tags:
      - document_formatters
      summary: Export document as Word (.docx) from markdown input
      description: 'Exports a document as Word (.docx) from markdown content.


        This endpoint accepts pre-formatted markdown content and converts it to a

        Word document using Pandoc. Mermaid diagrams are rendered as embedded images.


        **Plan restriction:** Requires Pro or Enterprise plan. Free users receive a

        403 error with PLAN_UPGRADE_REQUIRED.'
      operationId: export_docx_from_markdown
      parameters:
      - name: doc_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/app__models__enums__DocumentType'
          - type: 'null'
          description: Optional document type for filename generation
          title: Doc Type
        description: Optional document type for filename generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocxOutputRequest'
      responses:
        '200':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Internal server error
components:
  schemas:
    PDFJobStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - failed
      title: PDFJobStatus
      description: Status of a PDF generation job.
    AllPRDStepsDashedEnum:
      type: string
      enum:
      - executive-overview
      - user-personas
      - high-level-requirements
      - user-stories
      - security-requirements
      - system-architecture
      - data-models
      - user-interface
      - api-specifications
      - interface-specifications
      - integration-points
      - security-considerations
      - tech-user-stories
      - implementation-strategy
      - retriever-api-specification
      - retriever-interface-specification
      - retriever-data-models
      - retriever-classes
      - retriever-summary
      title: AllPRDStepsDashedEnum
      description: All PRD steps with dashed values.
    PDFAsyncResponse:
      properties:
        job_id:
          type: string
          maxLength: 64
          title: Job Id
          description: Unique job identifier
        status:
          $ref: '#/components/schemas/PDFJobStatus'
          description: Current status (pending)
        result_url:
          type: string
          title: Result Url
          description: Download endpoint for completed PDF
        stream_url:
          type: string
          title: Stream Url
          description: SSE streaming endpoint for real-time progress
        message:
          type: string
          title: Message
          description: Human-readable message
          default: PDF generation initiated
      type: object
      required:
      - job_id
      - status
      - result_url
      - stream_url
      title: PDFAsyncResponse
      description: Response for async PDF generation initiation.
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    app__models__enums__DocumentType:
      type: string
      enum:
      - prd
      - technical-spec
      - document-section
      title: DocumentType
      description: Enum for document types.
    DocxOutputRequest:
      properties:
        markdown:
          type: string
          title: Markdown
          description: Markdown content to convert
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Optional project ID for cache namespacing
      type: object
      required:
      - markdown
      title: DocxOutputRequest
      description: Request model for Word document (.docx) output from markdown input.
      examples:
      - markdown: '# My Document


          This is markdown content to export as Word.'
    DocumentFormatResponse:
      properties:
        markdown:
          type: string
          title: Markdown
          description: The formatted document in markdown format
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional metadata about the formatting operation
      type: object
      required:
      - markdown
      - metadata
      title: DocumentFormatResponse
      description: Response model for document formatting.
    TableOfContentsRequest:
      properties:
        markdown:
          type: string
          title: Markdown
          description: The markdown content to generate table of contents from
      type: object
      required:
      - markdown
      title: TableOfContentsRequest
      description: Request model for table of contents generation.
    ErrorBody:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional extra context for the error.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    PDFOutputRequest:
      properties:
        markdown:
          type: string
          title: Markdown
          description: Markdown content to convert
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Optional project ID for cache namespacing
      type: object
      required:
      - markdown
      title: PDFOutputRequest
      description: Request model for PDF output from markdown input.
      examples:
      - markdown: '# My Document


          This is markdown content from an artifact download.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter the Bearer token from Clerk authentication
x-tagGroups:
- name: Ingest Your Codebase
  tags:
  - vector_store
  - projects
  - pre_ingestion
  - reingestion
- name: Generate Code Intelligence
  tags:
  - documents
  - document_generation
  - document_formatters
  - prd
  - prd_version
  - tech_spec
  - quality_metrics
  - sample_projects
- name: Query Your Codebase
  tags:
  - conversations
  - workflows
  - discovery
  - context
  - artifacts
- name: Manage and Inspect Intelligence
  tags:
  - api_debugging
  - events
  - version
  - files
  - cache
  - token_tracking
- name: Authenticate and Manage Access
  tags:
  - clerk_authentication
  - github_webhooks
  - github_integration
  - organizations
  - api_key_management
  - mcp_token_management
  - user
- name: (Advanced) Prompt Tuning
  tags:
  - prompts
- name: MCP Protocol
  tags:
  - mcp_protocol
- name: Administration
  tags:
  - admin