CoreStory Files API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Files 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: Files
paths:
  /api/projects/{project_id}/file-manifest:
    get:
      tags:
      - Files
      summary: Get the complete file manifest for a project
      description: Returns a manifest of files discovered during pre-ingestion analysis. By default only included files are returned. Use include_excluded=true to also return excluded files. Use ingested_only=true to return only files successfully ingested into the vector store.
      operationId: get_project_file_manifest
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: include_excluded
        in: query
        required: false
        schema:
          type: boolean
          description: Include files excluded during pre-ingestion analysis
          default: false
          title: Include Excluded
        description: Include files excluded during pre-ingestion analysis
      - name: ingested_only
        in: query
        required: false
        schema:
          type: boolean
          description: Only return files successfully ingested into the vector store
          default: false
          title: Ingested Only
        description: Only return files successfully ingested into the vector store
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileManifestResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/file-content:
    get:
      tags:
      - Files
      summary: Stream file content from vector store by file path
      description: Retrieve the code content of a file from the vector store using its file path. Returns streaming response for memory efficiency.
      operationId: get_file_content
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: file_path
        in: query
        required: true
        schema:
          type: string
          description: The file path to retrieve content for
          title: File Path
        description: The file path to retrieve content for
      - name: start_line
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Starting line number (1-indexed, inclusive)
          title: Start Line
        description: Starting line number (1-indexed, inclusive)
      - name: end_line
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Ending line number (1-indexed, inclusive)
          title: End Line
        description: Ending line number (1-indexed, inclusive)
      responses:
        '200':
          description: Streaming file content
          content:
            application/json:
              schema: {}
            text/plain: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: File or vector store not found
  /api/projects/{project_id}/file-content/metadata:
    get:
      tags:
      - Files
      summary: Get file metadata from vector store
      description: Retrieve aggregated metadata for a file from the vector store including summaries, functions, classes, and interfaces.
      operationId: get_file_content_metadata
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: file_path
        in: query
        required: true
        schema:
          type: string
          description: The file path to retrieve metadata for
          title: File Path
        description: The file path to retrieve metadata for
      - name: start_line
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Starting line number (1-indexed, inclusive)
          title: Start Line
        description: Starting line number (1-indexed, inclusive)
      - name: end_line
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Ending line number (1-indexed, inclusive)
          title: End Line
        description: Ending line number (1-indexed, inclusive)
      responses:
        '200':
          description: File metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileContentMetadata'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: File or vector store not found
components:
  schemas:
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    FileManifestItem:
      properties:
        path:
          type: string
          title: Path
          description: Full file path relative to the repository root
        file_name:
          type: string
          title: File Name
          description: Base file name derived from path
        status:
          type: string
          enum:
          - included
          - excluded
          title: Status
          description: Whether the file was included or excluded during pre-ingestion
        ingested:
          type: boolean
          title: Ingested
          description: Whether the file has been ingested into the vector store
        exclusion_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Exclusion Reason
          description: Reason for exclusion, null for included files
        creation_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Creation Date
          description: File creation date (ISO 8601)
        last_modified_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Modified Date
          description: Last modified date (ISO 8601)
        first_ingested_at:
          anyOf:
          - type: string
          - type: 'null'
          title: First Ingested At
          description: When the file was first ingested (ISO 8601)
        last_ingested_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Ingested At
          description: When the file was last ingested (ISO 8601)
      type: object
      required:
      - path
      - file_name
      - status
      - ingested
      title: FileManifestItem
      description: A single file entry in the project file manifest.
    FunctionInfo:
      properties:
        name:
          type: string
          title: Name
          description: Function name
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
          description: AI-generated summary
      type: object
      required:
      - name
      title: FunctionInfo
      description: Function name and summary.
    FileManifestResponse:
      properties:
        project_id:
          type: integer
          title: Project Id
          description: Project ID
        total_files:
          type: integer
          title: Total Files
          description: Total number of files in the manifest
        included_files:
          type: integer
          title: Included Files
          description: Number of included files
        excluded_files:
          type: integer
          title: Excluded Files
          description: Number of excluded files
        ingestion_status_degraded:
          type: boolean
          title: Ingestion Status Degraded
          description: True when the vector store lookup failed and ingestion status could not be determined
          default: false
        files:
          items:
            $ref: '#/components/schemas/FileManifestItem'
          type: array
          title: Files
          description: List of file manifest entries
      type: object
      required:
      - project_id
      - total_files
      - included_files
      - excluded_files
      - files
      title: FileManifestResponse
      description: Complete file manifest for a project.
    ClassInfo:
      properties:
        name:
          type: string
          title: Name
          description: Class name
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
          description: AI-generated summary
      type: object
      required:
      - name
      title: ClassInfo
      description: Class name and summary.
    InterfaceInfo:
      properties:
        name:
          type: string
          title: Name
          description: Interface type (mainframe, desktop, web, mobile, terminal, api)
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
          description: Technology used
      type: object
      required:
      - name
      title: InterfaceInfo
      description: Interface name and summary.
    FileContentMetadata:
      properties:
        file_path:
          type: string
          title: File Path
          description: Full file path
        file_name:
          type: string
          title: File Name
          description: File name extracted from path
        file_type:
          anyOf:
          - type: string
          - type: 'null'
          title: File Type
          description: MIME type of the file (e.g. 'text/markdown')
        last_modified_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Modified Date
          description: Last modified date (ISO 8601)
        creation_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Creation Date
          description: File creation date (ISO 8601)
        first_ingested_at:
          anyOf:
          - type: string
          - type: 'null'
          title: First Ingested At
          description: When the file was first ingested (ISO 8601)
        last_ingested_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Ingested At
          description: When the file was last ingested (ISO 8601)
        start_line:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start Line
          description: Requested start line (1-indexed)
        end_line:
          anyOf:
          - type: integer
          - type: 'null'
          title: End Line
          description: Requested end line (1-indexed)
        github_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Github Url
          description: Direct GitHub URL to the file (with line range if specified)
        code_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Summary
          description: Aggregated code summary from chunks
        functions:
          items:
            $ref: '#/components/schemas/FunctionInfo'
          type: array
          title: Functions
          description: Functions in the file/range
        classes:
          items:
            $ref: '#/components/schemas/ClassInfo'
          type: array
          title: Classes
          description: Classes in the file/range
        interfaces:
          items:
            $ref: '#/components/schemas/InterfaceInfo'
          type: array
          title: Interfaces
          description: Interfaces in the file/range
        referenced_in_sections:
          items:
            $ref: '#/components/schemas/PRDReferenceContext'
          type: array
          title: Referenced In Sections
          description: Sections that reference this file
      type: object
      required:
      - file_path
      - file_name
      title: FileContentMetadata
      description: Metadata response for file content retrieval.
    PRDReferenceContext:
      properties:
        section_name:
          type: string
          title: Section Name
          description: Section name in dashed format (e.g. 'executive-overview', 'user-stories')
        reference_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Text
          description: Short description of what this file contributes to the section
        line_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line Number
          description: Line number in the file that was referenced
        index_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Index Id
          description: Array index of the entity within the section (e.g. user story index)
      type: object
      required:
      - section_name
      title: PRDReferenceContext
      description: A PRD section that references this file.
    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
  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