CoreStory Prd API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Prd 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
paths:
  /api/projects/{project_id}/prd/status:
    get:
      tags:
      - prd
      summary: Get the project's PRD generation status
      description: Get the project's PRD generation status.
      operationId: get_prd_status
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusSummary'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd:
    get:
      tags:
      - prd
      summary: Get the project's PRD (not tech spec) sections data
      description: Get all of the project's PRD sections (not Tech Spec sections).
      operationId: get_prd
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDSectionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/generate:
    post:
      tags:
      - prd
      summary: Generate the PRD sections (no Tech Spec sections) for the project
      description: 'Generates a high-level Product Requirements Document (PRD) focused on business and user requirements.

        It generates 5 sections: Executive Overview, User Personas, High-Level Requirements (Epics), User Stories, Security Requirements.


        The show_code_references flag (default: False) controls whether code references are included in user stories.

        When set to False, code references will be removed from both JSON and markdown output.


        The generate_toc flag (default: False) controls whether to include a table of contents in the markdown output.

        This parameter only has an effect when the format is set to "markdown". When format is "json", this parameter is ignored.'
      operationId: generate_prd
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: format
        in: query
        required: false
        schema:
          enum:
          - json
          - markdown
          type: string
          description: The format of the generated document
          default: json
          title: Format
        description: The format of the generated document
      - name: show_code_references
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to include code references in user stories
          default: false
          title: Show Code References
        description: Whether to include code references in user stories
      - name: generate_toc
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to generate a table of contents (only applies when format is 'markdown')
          default: false
          title: Generate Toc
        description: Whether to generate a table of contents (only applies when format is 'markdown')
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePRDRequest'
      responses:
        '200':
          description: A complete PRD in either JSON or Markdown format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDGenerateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/generate-all:
    post:
      tags:
      - prd
      summary: Generate all PRD and tech spec sections for the project
      description: (Re)generates all sections, runs in background.
      operationId: generate_all_prd_sections
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAllRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate All Prd Sections
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/context:
    get:
      tags:
      - prd
      summary: Get the context for the project's latest PRD
      description: 'Get the context for the project''s latest PRD.


        Args:

        project_id: ID of the Project


        Returns:

        PRDContextResponse: The PRD context with creation timestamp'
      operationId: get_prd_context
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: The PRD context with creation timestamp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDContextResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    post:
      tags:
      - prd
      summary: Set or update the context for the project's latest PRD
      description: 'Set or update the context for a specific PRD.


        Args:

        project_id: ID of the Project


        Returns:

        PRDContextResponse: The updated PRD context with creation timestamp'
      operationId: set_prd_context
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PRDContextRequest'
      responses:
        '200':
          description: The updated PRD context with creation timestamp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PRDContextResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/user-stories/catalog:
    get:
      tags:
      - prd
      summary: Get a catalog of user stories items for UI faceted browsing
      description: 'Returns unique, alpha-sorted catalogs lists, and counts for:

        - main_features: from high_level_requirements.features[*].category

        - epics: from high_level_requirements.features[*].name

        - personas: from user_personas.user_personas[*].name'
      operationId: get_user_stories_catalog
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get User Stories Catalog
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/{section_name}/generate:
    post:
      tags:
      - prd
      summary: Generate a specific PRD section
      operationId: generate_prd_section
      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/PRDStepsDashedEnum'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePRDSectionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Generate Prd Section
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/prd/{section_name}:
    patch:
      tags:
      - prd
      summary: Update the specified PRD section
      description: Get a single specified section for the project's base PRD (not tech spec).
      operationId: update_prd_section
      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/PRDStepsDashedEnum'
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Patch Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccessResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    get:
      tags:
      - prd
      summary: Get the specified PRD section
      description: Get a single specified section for the project's base PRD (not tech spec).
      operationId: get_prd_section
      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/PRDStepsDashedEnum'
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      - 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/PRDSingleSectionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    PRDContextResponse:
      properties:
        context:
          type: string
          title: Context
          description: The PRD context
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the context was created
      type: object
      required:
      - context
      - created_at
      title: PRDContextResponse
      description: Response model for PRD context.
    PRDCustomPromptRequest:
      properties:
        prompt:
          type: string
          title: Prompt
        replacement:
          type: boolean
          title: Replacement
      type: object
      required:
      - prompt
      - replacement
      title: PRDCustomPromptRequest
    JobStatusSummary:
      properties:
        status:
          type: string
          title: Status
          description: Current job status
        progress:
          type: number
          title: Progress
          description: Progress percentage (0-100)
          default: 0.0
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By
          description: User ID who triggered this job
        failure_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Type
          description: Short categorical failure tag set only when the job is FAILED. Lets the UI render category-specific guidance without parsing the message. See `app.orchestrations.ingestion.failure_handler.classify_failure` for the authoritative set of values.
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Reason
          description: Human-readable failure message safe to show in the UI. Set only when the job is FAILED.
      type: object
      required:
      - status
      title: JobStatusSummary
      description: Lightweight status + progress for a single job type (ingestion, PRD generation, etc.).
    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.'
    PRDGenerateResponse:
      properties:
        content:
          title: Content
          description: The generated document content (dict for JSON format, str for markdown format)
        format:
          type: string
          title: Format
          description: The format of the document (json or markdown)
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional metadata about the document
      type: object
      required:
      - content
      - format
      - metadata
      title: PRDGenerateResponse
      description: Response model for PRD generation
    GeneratePRDRequest:
      properties:
        custom_prompts:
          anyOf:
          - items:
              $ref: '#/components/schemas/GeneratePRDCustomPromptItem'
            type: array
          - type: 'null'
          title: Custom Prompts
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
      type: object
      title: GeneratePRDRequest
    GenerateAllRequest:
      properties:
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
      type: object
      title: GenerateAllRequest
    GeneratePRDSectionRequest:
      properties:
        custom_prompt:
          anyOf:
          - $ref: '#/components/schemas/PRDCustomPromptRequest'
          - type: 'null'
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
      type: object
      title: GeneratePRDSectionRequest
    PRDSectionsResponse:
      properties:
        executive_overview:
          anyOf:
          - type: string
          - type: 'null'
          title: Executive Overview
          description: Executive overview details
        user_personas:
          additionalProperties: true
          type: object
          title: User Personas
          description: User personas details
        high_level_requirements:
          additionalProperties: true
          type: object
          title: High Level Requirements
          description: High level requirements details
        user_stories:
          anyOf:
          - items: {}
            type: array
          - type: string
          title: User Stories
          description: User stories details
        security_requirements:
          additionalProperties: true
          type: object
          title: Security Requirements
          description: Security requirements details
        caveats:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Caveats
          description: Per-section provenance caveats keyed by section name. Only populated for sections whose evidence is documentation-only or mixed; absent when all sections are grounded in code or have no sources.
        prd_id:
          type: integer
          title: Prd Id
        prd_version_num:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prd Version Num
        prd_version_uid:
          anyOf:
          - type: string
          - type: 'null'
          title: Prd Version Uid
        generated_from_commit_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated From Commit Sha
        custom_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Job metadata including version and version_tag
      type: object
      required:
      - prd_id
      - created_at
      title: PRDSectionsResponse
    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
    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.
    PRDStepsDashedEnum:
      type: string
      enum:
      - executive-overview
      - user-personas
      - high-level-requirements
      - user-stories
      - security-requirements
      title: PRDStepsDashedEnum
      description: All PRD steps with dashed values.
    PRDSingleSectionResponse:
      properties:
        prd_id:
          type: integer
          title: Prd Id
        created_at:
          type: string
          format: date-time
          title: Created At
        custom_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt
        can_regenerate:
          type: boolean
          title: Can Regenerate
          default: false
        stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Stats
          description: Optional stats such as total_user_stories and filtered_user_stories.
        prd_version_num:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prd Version Num
        prd_version_uid:
          anyOf:
          - type: string
          - type: 'null'
          title: Prd Version Uid
        language:
          anyOf:
          - $ref: '#/components/schemas/LanguageInfo'
          - type: 'null'
          description: Language the section was generated in, if non-English.
        executive_overview:
          anyOf:
          - type: string
          - type: 'null'
          title: Executive Overview
        user_personas:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: User Personas
        high_level_requirements:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: High Level Requirements
        user_stories:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: string
          - type: 'null'
          title: User Stories
        security_requirements:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Security Requirements
        pagination:
          anyOf:
          - $ref: '#/components/schemas/PaginationMeta'
          - type: 'null'
        caveat:
          anyOf:
          - type: string
          - type: 'null'
          title: Caveat
          description: Provenance caveat for the requested section. Populated when the section's evidence is documentation-only or mixed; absent otherwise.
      type: object
      required:
      - prd_id
      - created_at
      title: PRDSingleSectionResponse
      description: 'Used for endpoint to get a single section of a PRD.

        Only 1 section is ever output, endpoint sets "don''t output None".

        # AKA: Only output the property if it exists.'
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    GeneratePRDCustomPromptItem:
      properties:
        section_name:
          $ref: '#/components/schemas/PRDStepsDashedEnum'
        prompt:
          type: string
          title: Prompt
        replacement:
          type: boolean
          title: Replacement
          default: false
      type: object
      required:
      - section_name
      - prompt
      title: GeneratePRDCustomPromptItem
    PaginationMeta:
      properties:
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        size:
          type: integer
          title: Size
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - total
      - page
      - size
      - pages
      title: PaginationMeta
    PRDContextRequest:
      properties:
        context:
          type: string
          title: Context
          description: The context to set for the PRD
          example: This is the context for the PRD that will be used for document generation.
      type: object
      required:
      - context
      title: PRDContextRequest
      description: Request model for setting PRD context.
  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