CoreStory Prd Version API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Prd Version 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: prd_version
paths:
  /api/projects/{project_id}/prd/versions:
    get:
      tags:
      - prd_version
      summary: List the versions of the given PRD (with per-version diffs vs previous)
      description: 'List all versions for the project''s PRD (most recent first) and, for each version,

        include the list of section names that differ compared to the previous version

        in that ordered list. The oldest version has an empty diff.'
      operationId: list_prd_versions
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - 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/PRDVersionItemWithDiffListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/import-steps:
    post:
      tags:
      - prd_version
      summary: Bulk-import PRD/TechSpec step content
      description: 'Bulk-create PRDStep rows from a flat dict of dashed step names to content.

        Does not create a version — call create-from-latest afterwards.'
      operationId: import_prd_steps
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportStepsRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStepsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/versions/create-from-latest:
    post:
      tags:
      - prd_version
      summary: Create a new PRD version from the latest steps
      description: Snapshot the latest PRD steps into a new PRDVersion and set it as current.
      operationId: create_prd_version_from_latest
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/versions/{version_uid}:
    delete:
      tags:
      - prd_version
      summary: Delete a PRD Version by uid
      description: Delete a PRD version by UID (must belong to this project's PRD).
      operationId: delete_prd_version
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version Uid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccessResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    patch:
      tags:
      - prd_version
      summary: Update a PRD Version (only certain allowed fields)
      description: 'Update allowed fields on a PRD Version.

        Currently allowed fields: title'
      operationId: update_prd_version
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version Uid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PRDVersionUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/versions/diff:
    get:
      tags:
      - prd_version
      summary: Get section names that changed between two PRD versions
      description: 'Return a list of section names that differ between two PRD versions.

        Example:

        { "changed_sections": ["executive-overview", "data-models", "user-stories"] }'
      operationId: diff_prd_versions
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: from_version
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Source PRD version UID
          title: From Version
        description: Source PRD version UID
      - name: to_version
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Target PRD version UID
          title: To Version
        description: Target PRD version UID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionDiffResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/versions/{version_uid}/promote:
    post:
      tags:
      - prd_version
      summary: Promote a full PRD version (PRD + tech specs) to be the current one
      description: Make the given PRD version (by UID) the current version for this project's PRD.
      operationId: promote_prd_version
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version Uid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/versions/{version_uid}/{section_name}/promote:
    post:
      tags:
      - prd_version
      summary: Promote a single section from an old version by cloning into a new current…
      description: 'Clone the given PRD section from the specified PRD version (by UID),

        create a NEW PRDVersion using that section, set it current, and return the new version.'
      operationId: promote_prd_section
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version Uid
      - name: section_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/DocumentSectionsDashedEnum'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/tech-spec/versions/{version_uid}/{section_name}/promote:
    post:
      tags:
      - prd_version
      summary: Promote a single tech-spec section from an old version by cloning into a new…
      description: 'Clone the given tech-spec section from the specified PRD version (by UID),

        create a NEW PRDVersion using that section, set it current, and return the new version.'
      operationId: promote_tech_spec_section
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version Uid
      - name: section_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/TechSpecStepsDashedEnum'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDVersionItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/{section_name}/versions:
    get:
      tags:
      - prd_version
      summary: List PRD versions that include the given section
      description: 'Return PRD versions (newest first) that contain the specified section.

        Uses PRDVersionStepService.list_versions_for_step(prd_id, step_name) to find matches.'
      operationId: list_prd_section_versions
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: section_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/DocumentSectionsDashedEnum'
      - 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/PRDVersionItemListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/tech-spec/{section_name}/versions:
    get:
      tags:
      - prd_version
      summary: List PRD versions that include the given tech-spec section
      description: 'Return PRD versions (newest first) that contain the specified section.

        Uses PRDVersionStepService.list_versions_for_step(prd_id, step_name) to find matches.'
      operationId: list_tech_spec_section_versions
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: section_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/TechSpecStepsDashedEnum'
      - 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/PRDVersionItemListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    PRDVersionDiffResponse:
      properties:
        changed_sections:
          items:
            type: string
          type: array
          title: Changed Sections
          description: Section names that differ from version to version.
      type: object
      title: PRDVersionDiffResponse
    TechSpecStepsDashedEnum:
      type: string
      enum:
      - system-architecture
      - data-models
      - user-interface
      - api-specifications
      - interface-specifications
      - integration-points
      - security-considerations
      - tech-user-stories
      - implementation-strategy
      title: TechSpecStepsDashedEnum
      description: All tech spec steps with dashed values.
    LanguageInfo:
      properties:
        code:
          type: string
          title: Code
          description: BCP-47 language code (ja, es, fr-CA).
        name:
          type: string
          title: Name
          description: Language name in its native script (English, français (Canada)).
      type: object
      required:
      - code
      - name
      title: LanguageInfo
      description: Language information with code and native display name.
    PRDVersionItemWithDiffListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PRDVersionItemWithDiffResponse'
          type: array
          title: Results
          description: List of PRD versions
        pagination:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pagination
      type: object
      required:
      - results
      title: PRDVersionItemWithDiffListResponse
      description: Response model for paginated list of versions for a PRD.
    PRDVersionItemWithDiffResponse:
      properties:
        uid:
          type: string
          title: Uid
        prd_id:
          type: integer
          title: Prd Id
        version_num:
          type: integer
          title: Version Num
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        parent_version_uid:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Version Uid
        generated_from_commit_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated From Commit Sha
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
        created_by_fullname:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Fullname
        created_at:
          type: string
          format: date-time
          title: Created At
        active_version:
          type: boolean
          title: Active Version
          default: false
        custom_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt
        changed_sections:
          items:
            type: string
          type: array
          title: Changed Sections
          description: Section names that differ from the previous version in sequence
        languages:
          items:
            $ref: '#/components/schemas/LanguageInfo'
          type: array
          title: Languages
          description: Unique languages used across all sections in this version.
      type: object
      required:
      - uid
      - prd_id
      - version_num
      - created_at
      title: PRDVersionItemWithDiffResponse
      description: 'Subclass the item fields above and add the diff''d sections from the previous version

        in the history of versions.'
    ImportStepsResponse:
      properties:
        steps_created:
          type: integer
          title: Steps Created
        step_names:
          items:
            type: string
          type: array
          title: Step Names
          description: Dashed step names that were created.
      type: object
      required:
      - steps_created
      - step_names
      title: ImportStepsResponse
      description: Response for a successful import-steps call.
    PRDVersionItemListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PRDVersionItemResponse'
          type: array
          title: Results
          description: List of versions for a given section
        pagination:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pagination
      type: object
      required:
      - results
      title: PRDVersionItemListResponse
      description: Response model for paginated list of versions for a given section.
    DocumentSectionsDashedEnum:
      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
      title: DocumentSectionsDashedEnum
      description: PRD + tech-spec sections only (no retriever). Use for user-facing endpoints.
    PRDVersionItemResponse:
      properties:
        uid:
          type: string
          title: Uid
        prd_id:
          type: integer
          title: Prd Id
        version_num:
          type: integer
          title: Version Num
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        parent_version_uid:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Version Uid
        generated_from_commit_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated From Commit Sha
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
        created_by_fullname:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Fullname
        created_at:
          type: string
          format: date-time
          title: Created At
        active_version:
          type: boolean
          title: Active Version
          default: false
        custom_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt
        language:
          anyOf:
          - $ref: '#/components/schemas/LanguageInfo'
          - type: 'null'
      type: object
      required:
      - uid
      - prd_id
      - version_num
      - created_at
      title: PRDVersionItemResponse
    ImportStepsRequest:
      additionalProperties: true
      type: object
      title: ImportStepsRequest
      description: 'Request body for bulk-importing PRD/TechSpec step content.


        Accepts a flat JSON object mapping dashed step names to content.

        Validates that the dict is non-empty and all keys are recognised step names.'
    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
    PRDVersionUpdateRequest:
      properties:
        title:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Title
          description: New title for this PRD version
      additionalProperties: false
      type: object
      title: PRDVersionUpdateRequest
      description: Allowed updatable fields on a PRD Version.
    BasicSuccessResponse:
      properties:
        detail:
          type: string
          title: Detail
          default: success
      type: object
      title: BasicSuccessResponse
      description: 'Use this for returns for deletes and patches.

        UI ALWAYS needs some payload return. This just standarizes it.'
  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