CoreStory System Overview API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation System Overview 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: system_overview
paths:
  /api/projects/{project_id}/system-overview:
    get:
      tags:
      - system_overview
      summary: Get System Intelligence Overview for a project
      description: Returns the complete System Intelligence Overview including architecture classification, tech stack, code quality, and metadata. Returns 202 if analysis is still in progress.
      operationId: get_system_overview
      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/SystemOverviewResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '202':
          description: Analysis is still in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemOverviewProcessingResponse'
  /api/projects/{project_id}/system-overview/regenerate/estimate:
    get:
      tags:
      - system_overview
      summary: Estimate CIU cost for SIO regeneration
      operationId: estimate_sio_regeneration
      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/RegenerationEstimateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/system-overview/regenerate:
    post:
      tags:
      - system_overview
      summary: Trigger SIO regeneration
      description: Re-runs the SIO analysis pipeline. Deducts CIUs from the organization's balance.
      operationId: regenerate_system_overview
      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/RegenerationTriggerResponse'
        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
    CodeQualityOverview:
      properties:
        indicators:
          additionalProperties: true
          type: object
          title: Indicators
      additionalProperties: true
      type: object
      title: CodeQualityOverview
      description: Thin wrapper over code_quality_indicators from code_analysis.
    SystemOverviewResponse:
      properties:
        architecture:
          anyOf:
          - $ref: '#/components/schemas/ArchitectureOverview'
          - type: 'null'
        tech_stack:
          anyOf:
          - $ref: '#/components/schemas/TechStackOverview'
          - type: 'null'
        code_quality:
          anyOf:
          - $ref: '#/components/schemas/CodeQualityOverview'
          - type: 'null'
        health_signals:
          anyOf:
          - {}
          - type: 'null'
          title: Health Signals
          description: Not yet implemented
        security:
          anyOf:
          - {}
          - type: 'null'
          title: Security
          description: Not yet implemented
        suggested_actions:
          anyOf:
          - {}
          - type: 'null'
          title: Suggested Actions
          description: Not yet implemented
        metadata:
          $ref: '#/components/schemas/SIOMetadata'
      additionalProperties: false
      type: object
      required:
      - metadata
      title: SystemOverviewResponse
      description: Complete SIO payload returned when analysis is available.
    RegenerationTriggerResponse:
      properties:
        status:
          type: string
          const: started
          title: Status
          default: started
        message:
          type: string
          title: Message
          default: System Intelligence Overview regeneration has been started
        estimated_cost:
          type: number
          title: Estimated Cost
          description: CIU cost deducted for this regeneration
        job_id:
          type: string
          title: Job Id
          description: SOTJ job id tracking
      type: object
      required:
      - estimated_cost
      - job_id
      title: RegenerationTriggerResponse
      description: Returned when regeneration is successfully triggered.
    RegenerationEstimateResponse:
      properties:
        estimated_cost:
          type: number
          title: Estimated Cost
          description: CIU cost for regeneration
        available_balance:
          type: number
          title: Available Balance
          description: Organization's current available CIUs
        can_regenerate:
          type: boolean
          title: Can Regenerate
          description: Whether the organization has enough CIUs
      type: object
      required:
      - estimated_cost
      - available_balance
      - can_regenerate
      title: RegenerationEstimateResponse
      description: CIU cost estimate for SIO regeneration.
    ArchitectureOverview:
      properties:
        pattern_id:
          type: string
          title: Pattern Id
        label:
          type: string
          title: Label
        score:
          type: number
          title: Score
        tier:
          type: string
          title: Tier
        explanation:
          anyOf:
          - $ref: '#/components/schemas/ArchitectureExplanation'
          - type: 'null'
        low_confidence_guidance:
          anyOf:
          - type: string
          - type: 'null'
          title: Low Confidence Guidance
      type: object
      required:
      - pattern_id
      - label
      - score
      - tier
      title: ArchitectureOverview
    ArchitectureExplanation:
      properties:
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        detected_signals:
          items:
            type: string
          type: array
          title: Detected Signals
        key_drivers:
          items:
            type: string
          type: array
          title: Key Drivers
        alternative_interpretation:
          anyOf:
          - $ref: '#/components/schemas/ArchitectureAlternative'
          - type: 'null'
        confidence_alignment:
          anyOf:
          - type: string
          - type: 'null'
          title: Confidence Alignment
      type: object
      title: ArchitectureExplanation
    ArchitectureAlternative:
      properties:
        pattern_id:
          type: string
          title: Pattern Id
        label:
          type: string
          title: Label
        score:
          type: number
          title: Score
        tier:
          type: string
          title: Tier
      type: object
      required:
      - pattern_id
      - label
      - score
      - tier
      title: ArchitectureAlternative
    SIOMetadata:
      properties:
        generated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Generated At
        snapshot_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Snapshot Fingerprint
          description: Commit SHA of the ingested codebase version
        is_stale:
          type: boolean
          title: Is Stale
          default: false
        schema_version:
          type: string
          title: Schema Version
          default: '1.0'
      type: object
      title: SIOMetadata
    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
    TechStackOverview:
      properties:
        primary_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Language
        additional_languages:
          items:
            type: string
          type: array
          title: Additional Languages
        frameworks:
          additionalProperties:
            items:
              additionalProperties: true
              type: object
            type: array
          type: object
          title: Frameworks
          description: 'Keyed by bucket: frontend, backend, state, styling, build'
        infrastructure:
          additionalProperties:
            items:
              additionalProperties: true
              type: object
            type: array
          type: object
          title: Infrastructure
          description: 'Keyed by category: containerization, ci_cd, iac, cloud_sdks'
        dependencies_count:
          type: integer
          title: Dependencies Count
          description: Total number of manifest + inferred dependencies
          default: 0
      type: object
      title: TechStackOverview
      description: Reshaped view of language_breakdown + framework_tech_stack + infrastructure + dependencies.
    SystemOverviewProcessingResponse:
      properties:
        status:
          type: string
          const: processing
          title: Status
          default: processing
        message:
          type: string
          title: Message
          default: Analysis is still in progress
      type: object
      title: SystemOverviewProcessingResponse
      description: Returned with HTTP 202 when the analysis pipeline is still running.
  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