CoreStory Tech Spec API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Tech Spec 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: tech_spec
paths:
  /api/projects/{project_id}/tech-spec:
    get:
      tags:
      - tech_spec
      summary: Get the project's Tech Spec (not base PRD) sections data
      description: Get all of the project's Tech Spec sections (not base PRD sections).
      operationId: get_tech_spec
      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/TechSpecSectionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/tech-spec/status:
    get:
      tags:
      - tech_spec
      summary: Get the project's tech-spec generation status
      description: Get the project's tech spec generation status.
      operationId: get_tech_spec_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}/tech-spec/generate:
    post:
      tags:
      - tech_spec
      summary: Generate the Tech Spec sections (no base PRD sections) for the project
      description: 'Generates a detailed Technical Specification Document focused on implementation details, including:

        - System Architecture

        - Data Models and ERDs

        - API Specifications

        - Integration Points

        - Security Considerations

        - Implementation Strategy


        This document is suitable for technical teams, developers, and system architects.


        The endpoint accepts an optional context object that can include:

        - features: Pre-defined features to use for generation


        If features are not provided, they will be generated automatically.


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

        The generate_toc flag (default: False) controls whether to include a table of contents in the markdown output.'
      operationId: generate_tech_spec
      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/GenerateTechSpecRequest'
      responses:
        '200':
          description: A complete technical specification 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:
      - tech_spec
      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}/tech-spec/tech-user-stories/catalog:
    get:
      tags:
      - tech_spec
      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_tech_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 Tech User Stories Catalog
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/tech-spec/{section_name}/generate:
    post:
      tags:
      - tech_spec
      summary: Generate a specific Tech Spec section
      operationId: generate_tech_spec_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/TechSpecStepsDashedEnum'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePRDSectionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Generate Tech Spec Section
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/tech-spec/{section_name}:
    patch:
      tags:
      - tech_spec
      summary: Update the specified Tech Spec section
      description: Get a single specified section for the project's base PRD (not tech spec).
      operationId: update_tech_spec_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/TechSpecStepsDashedEnum'
      - 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:
      - tech_spec
      summary: Get the specified Tech Spec section
      description: Get a single specified section for the project's PRD Tech Spec (not base PRD section).
      operationId: get_tech_spec_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/TechSpecStepsDashedEnum'
      - 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/TechSpecSingleSectionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    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
    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
    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.).
    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
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    TechnicalRequirements:
      properties:
        requirement:
          type: string
          title: Requirement
          description: Technical requirements for the user story.
        uml_diagram:
          anyOf:
          - type: string
          - type: 'null'
          title: Uml Diagram
          description: UML diagram for the user story.
          default: ''
        sequence_diagram:
          anyOf:
          - type: string
          - type: 'null'
          title: Sequence Diagram
          description: Sequence diagram for the user story.
          default: ''
        reference:
          items:
            $ref: '#/components/schemas/Reference'
          type: array
          title: Reference
          description: Reference to the file where the technical requirements were found.
      additionalProperties: false
      type: object
      required:
      - requirement
      - reference
      title: TechnicalRequirements
    TechSpecSectionsResponse:
      properties:
        system_architecture:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: System Architecture
          description: System architecture details
        data_models:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Data Models
          description: Data models details
        user_interface:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: User Interface
          description: User interface details
        api_specifications:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Api Specifications
          description: API specifications details
        interface_specifications:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Interface Specifications
          description: Interface specifications details
        integration_points:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Integration Points
          description: Integration points details
        security_considerations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Security Considerations
          description: Security considerations details
        implementation_strategy:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Implementation Strategy
          description: Implementation strategy details
        tech_user_stories:
          anyOf:
          - items: {}
            type: array
          - type: string
          title: Tech User Stories
          description: User stories 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: TechSpecSectionsResponse
    Reference:
      properties:
        file_name:
          type: string
          title: File Name
          description: Name of the file where the reference was found (just the filename, e.g., 'COCRDLIC.cbl').
        line_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line Number
          description: Line number where the reference was found in the code.
        reference_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Text
          description: Textual content of the reference. Class, method name, or other relevant information.
        file_path:
          anyOf:
          - type: string
          - type: 'null'
          title: File Path
          description: 'Full relative path to the file from repository root (e.g., ''app/cbl/COCRDLIC.cbl''). Extract from the Source: lines in the context if available.'
      type: object
      required:
      - file_name
      title: Reference
    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.'
    TechnicalSpecContext:
      properties:
        features:
          anyOf:
          - items:
              $ref: '#/components/schemas/Feature-Input'
            type: array
          - type: 'null'
          title: Features
          description: Optional list of features to use for generation
        user_stories:
          anyOf:
          - items:
              $ref: '#/components/schemas/UserStory'
            type: array
          - type: 'null'
          title: User Stories
          description: Optional list of user stories to generate code from
      type: object
      title: TechnicalSpecContext
      description: Context model for technical specification generation.
    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.
    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
    Feature-Input:
      properties:
        name:
          type: string
          title: Name
          description: Name of the feature
        description:
          type: string
          title: Description
          description: Description of the feature
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: Category of the feature
      type: object
      required:
      - name
      - description
      title: Feature
      description: Model for a feature in the technical specification.
    UserStory:
      properties:
        epic_name:
          type: string
          title: Epic Name
          description: Name of the Epic that is grouping multiple user stories.
        title:
          type: string
          title: Title
          description: Title of the user story.
        description:
          type: string
          title: Description
          description: Description of the user story.
        business_rules:
          items:
            type: string
          type: array
          title: Business Rules
          description: If applicable, the business rules for the user story.
        acceptance_criteria:
          items:
            type: string
          type: array
          title: Acceptance Criteria
          description: Acceptance criteria for the user story.
        references:
          items:
            $ref: '#/components/schemas/NewReference'
          type: array
          title: References
          description: Reference to the file where the user story was found.
        technical_requirements:
          anyOf:
          - $ref: '#/components/schemas/TechnicalRequirements'
          - type: 'null'
          description: Technical requirements for the user story.
        user_persona:
          anyOf:
          - type: string
          - type: 'null'
          title: User Persona
          description: User persona associated with the user story.
      additionalProperties: false
      type: object
      required:
      - epic_name
      - title
      - description
      - business_rules
      - acceptance_criteria
      - references
      - user_persona
      title: UserStory
    TechSpecSingleSectionResponse:
      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
        prd_version_num:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prd Version Num
        prd_version_uid:
          anyOf:
          - type: string
          - type: 'null'
          title: Prd Version Uid
        stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Stats
          description: Optional stats such as total_user_stories and filtered_user_stories.
        language:
          anyOf:
          - $ref: '#/components/schemas/LanguageInfo'
          - type: 'null'
          description: Language the section was generated in, if non-English.
        system_architecture:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: System Architecture
        data_models:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Data Models
        user_interface:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: User Interface
        api_specifications:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Api Specifications
        interface_specifications:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Interface Specifications
        integration_points:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Integration Points
        security_considerations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Security Considerations
        implementation_strategy:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          - type: 'null'
          title: Implementation Strategy
        tech_user_stories:
          anyOf:
          - items: {}
            type: array
          - type: string
          - type: 'null'
          title: Tech User Stories
        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: TechSpecSingleSectionResponse
      description: 'Used for endpoint to get a single section of a tech spec.

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

        # AKA: Only output the property if it exists.'
    GenerateTechSpecCustomPromptItem:
      properties:
        section_name:
          $ref: '#/components/schemas/TechSpecStepsDashedEnum'
        prompt:
          type: string
          title: Prompt
        replacement:
          type: boolean
          title: Replacement
          default: false
      type: object
      required:
      - section_name
      - prompt
      title: GenerateTechSpecCustomPromptItem
    NewReference:
      properties:
        file_name:
          type: string
          title: File Name
          description: Name of the file where the reference was found.
        line_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line Number
          description: Line number where the reference was found.
        reference_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Text
          description: Actual code from the file.
      additionalProperties: false
      type: object
      required:
      - file_name
      title: NewReference
    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.
    GenerateTechSpecRequest:
      properties:
        custom_prompts:
          anyOf:
          - items:
              $ref: '#/components/schemas/GenerateTechSpecCustomPromptItem'
            type: array
          - type: 'null'
          title: Custom Prompts
        context:
          anyOf:
          - $ref: '#/components/schemas/TechnicalSpecContext'
          - type: 'null'
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
      type: object
      title: GenerateTechSpecRequest
  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