CoreStory Reingestion API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Reingestion 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: reingestion
paths:
  /api/projects/{project_id}/reingestion/analyze:
    post:
      tags:
      - reingestion
      summary: Start pre-reingestion analysis for an existing project
      description: 'Start analysis of an existing project''s codebase for reingestion.

        Returns a job ID that can be polled for status and results.'
      operationId: start_reingestion_analysis
      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/ReingestionAnalysisResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/analyze/{job_id}/status:
    get:
      tags:
      - reingestion
      summary: Get reingestion analysis job status
      description: Get the status of a reingestion analysis job.
      operationId: get_reingestion_status
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReingestionAnalysisResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/analyze/{job_id}/coverage:
    get:
      tags:
      - reingestion
      summary: Get coverage results from reingestion analysis
      description: 'Get coverage results from a reingestion analysis job.


        Includes file change summary (added/modified/removed) and CIU cost

        estimate when the analysis was run for an existing project (reingestion).'
      operationId: get_reingestion_coverage
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReingestionAnalysisCoverageResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/analyze/{job_id}/excluded-files:
    get:
      tags:
      - reingestion
      summary: Get excluded file paths from reingestion analysis
      description: Get the list of excluded file paths from a reingestion analysis job.
      operationId: get_reingestion_excluded_files
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job 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: 100
          title: Size
        description: Items per page
      - name: file_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter files by name
          title: File Name
        description: Filter files by name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFilePathResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/analyze/{job_id}/included-files:
    get:
      tags:
      - reingestion
      summary: Get included file paths from reingestion analysis
      description: Get the list of included file paths from a reingestion analysis job.
      operationId: get_reingestion_included_files
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job 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: 100
          title: Size
        description: Items per page
      - name: file_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter files by name
          title: File Name
        description: Filter files by name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFilePathResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/analyze/{job_id}:
    delete:
      tags:
      - reingestion
      summary: Delete a reingestion analysis job
      description: Delete a reingestion analysis job and its associated files.
      operationId: delete_reingestion_job
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '204':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/reingestion/trigger:
    post:
      tags:
      - reingestion
      summary: Trigger full reingestion for an existing project
      description: 'Trigger full reingestion of an existing project''s codebase.


        This will:

        1. Delete the existing vector store

        2. Re-clone and ingest the codebase

        3. Optionally regenerate PRD/TechSpec documents

        4. Create a new version entry


        Set `force=true` in the body to re-process every document instead of skipping

        files that already exist in the vector store. Use after extractor/schema changes

        when existing chunks need to be re-extracted.'
      operationId: trigger_reingestion
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReingestionTriggerRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReingestionTriggerResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/ingestion-events:
    get:
      tags:
      - reingestion
      summary: List ingestion events for a project
      description: List ingestion events for a project, ordered most recent first.
      operationId: list_ingestion_events
      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: 50
          title: Size
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_IngestionEventResponse_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/ingestion-events/{event_id}/doc-impact:
    get:
      tags:
      - reingestion
      summary: Doc-section impact (added/modified/removed) for an ingestion event
      description: Return which PRD/Tech Spec sections changed when this ingestion event regenerated docs.
      operationId: get_ingestion_event_doc_impact
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: event_id
        in: path
        required: true
        schema:
          type: integer
          title: Event Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocImpactResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    FileChangeSummary:
      properties:
        added_count:
          type: integer
          title: Added Count
          default: 0
        modified_count:
          type: integer
          title: Modified Count
          default: 0
        removed_count:
          type: integer
          title: Removed Count
          default: 0
      type: object
      title: FileChangeSummary
      description: Summary counts of file changes between last ingestion and latest commit.
    FileChanges:
      properties:
        added:
          items:
            type: string
          type: array
          title: Added
        modified:
          items:
            type: string
          type: array
          title: Modified
        removed:
          items:
            type: string
          type: array
          title: Removed
      type: object
      title: FileChanges
      description: Categorized file paths changed between last ingestion and latest commit.
    ReingestionTriggerRequest:
      properties:
        regenerate_docs:
          type: boolean
          title: Regenerate Docs
          description: Whether to regenerate PRD/TechSpec after ingestion
          default: false
        application_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Application Context
          description: Update project application context before reingestion
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: BCP-47 language code for document generation (ja, es, fr-CA).
        force:
          type: boolean
          title: Force
          description: Force re-ingestion of every document instead of skipping ones already in the vector store. Use this after extractor/schema changes when existing chunks need to be re-processed.
          default: false
      type: object
      title: ReingestionTriggerRequest
      description: Request to trigger reingestion
    PaginatedResponse_IngestionEventResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/IngestionEventResponse'
          type: array
          title: Items
          description: List of items
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata
      type: object
      required:
      - items
      - pagination
      title: PaginatedResponse[IngestionEventResponse]
    ReingestionTriggerResponse:
      properties:
        message:
          type: string
          title: Message
        project_id:
          type: integer
          title: Project Id
        status:
          type: string
          title: Status
          default: started
        regenerate_docs:
          type: boolean
          title: Regenerate Docs
          description: Whether document regeneration was requested
          default: false
        force:
          type: boolean
          title: Force
          description: Whether force re-ingestion was requested
          default: false
        prd_job_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prd Job Id
          description: SOTJ job ID for PRD generation (if regenerate_docs=true)
        tech_spec_job_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tech Spec Job Id
          description: SOTJ job ID for tech spec generation (if regenerate_docs=true)
      type: object
      required:
      - message
      - project_id
      title: ReingestionTriggerResponse
      description: Response when reingestion is triggered
    DocImpactGroup:
      properties:
        sections_added:
          items:
            type: string
          type: array
          title: Sections Added
          description: Sections present only in the new version.
        sections_modified:
          items:
            type: string
          type: array
          title: Sections Modified
          description: Sections whose content changed.
        sections_removed:
          items:
            type: string
          type: array
          title: Sections Removed
          description: Sections present only in the old version.
      type: object
      title: DocImpactGroup
      description: Section-level changes for a single document (PRD or Tech Spec).
    PaginatedFilePathResponse:
      properties:
        results:
          items:
            type: string
          type: array
          title: Results
          description: List of filepaths in pre-ingestion job
        pagination:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pagination
      type: object
      required:
      - results
      - pagination
      title: PaginatedFilePathResponse
    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
    DocImpact:
      properties:
        prd:
          $ref: '#/components/schemas/DocImpactGroup'
        tech_spec:
          $ref: '#/components/schemas/DocImpactGroup'
      type: object
      title: DocImpact
      description: Doc-section changes an ingestion event produced, grouped by document.
    IngestionEventResponse:
      properties:
        id:
          type: integer
          title: Id
        project_id:
          type: integer
          title: Project Id
        triggered_at:
          type: string
          format: date-time
          title: Triggered At
        trigger_type:
          $ref: '#/components/schemas/TriggerType'
        commit_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Commit Sha
        branch:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By
        files_added:
          items:
            type: string
          type: array
          title: Files Added
        files_modified:
          items:
            type: string
          type: array
          title: Files Modified
        files_removed:
          items:
            type: string
          type: array
          title: Files Removed
        regenerated_docs:
          type: boolean
          title: Regenerated Docs
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        failed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Failed At
        failure_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Type
          description: Short categorical reason for failure (e.g. 'github_auth', 'timeout').
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Reason
          description: User-safe explanation of the failure.
      type: object
      required:
      - id
      - project_id
      - triggered_at
      - trigger_type
      - regenerated_docs
      title: IngestionEventResponse
    PreIngestionStatus:
      type: string
      enum:
      - started
      - cloning
      - parsing
      - analyzed
      - completed
      - failed
      title: PreIngestionStatus
      description: PreIngestion status enumeration
    DocImpactResponse:
      properties:
        doc_impact:
          $ref: '#/components/schemas/DocImpact'
      type: object
      title: DocImpactResponse
    ReingestionAnalysisResponse:
      properties:
        job_id:
          type: integer
          title: Job Id
        status:
          $ref: '#/components/schemas/PreIngestionStatus'
        progress:
          type: number
          title: Progress
          description: Progress percentage 0-100
          default: 0.0
        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.utils.pre_ingestion.classify_pre_ingestion_failure` for the authoritative set of values.
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Reason
          description: Human-readable, sanitized failure message safe to show in the UI. Set only when the job is FAILED.
      type: object
      required:
      - job_id
      - status
      title: ReingestionAnalysisResponse
      description: Response for pre-reingestion analysis
    TriggerType:
      type: string
      enum:
      - manual
      - automatic
      title: TriggerType
      description: How an ingestion event was triggered.
    CIUEstimate:
      properties:
        min:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Min
          description: Minimum estimated CIU cost
        max:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Max
          description: Maximum estimated CIU cost
      type: object
      required:
      - min
      - max
      title: CIUEstimate
      description: Estimated CIU cost for reingestion.
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ReingestionAnalysisCoverageResponse:
      properties:
        total_files:
          type: integer
          title: Total Files
        total_directories:
          type: integer
          title: Total Directories
        file_coverage:
          type: number
          title: File Coverage
          description: Percentage of files that will be ingested
        included_count:
          additionalProperties: true
          type: object
          title: Included Count
          description: File types included with counts
        excluded_count:
          additionalProperties: true
          type: object
          title: Excluded Count
          description: File types excluded with counts
        exclusion_reasons:
          additionalProperties: true
          type: object
          title: Exclusion Reasons
          description: Breakdown by exclusion reason
        files:
          anyOf:
          - $ref: '#/components/schemas/FileChanges'
          - type: 'null'
          description: Files added/modified/removed since last ingestion
        summary:
          anyOf:
          - $ref: '#/components/schemas/FileChangeSummary'
          - type: 'null'
          description: Counts of added/modified/removed files
        last_synced_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Synced Commit
          description: Commit SHA of last ingestion
        latest_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Commit
          description: HEAD commit SHA of the repo
        estimated_cius:
          anyOf:
          - $ref: '#/components/schemas/CIUEstimate'
          - type: 'null'
          description: Estimated CIU cost range for reingestion
      type: object
      required:
      - total_files
      - total_directories
      - file_coverage
      - included_count
      - excluded_count
      - exclusion_reasons
      title: ReingestionAnalysisCoverageResponse
      description: Coverage results from analysis, including file change summary and CIU estimate.
    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
  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