CoreStory Files API

The files API from CoreStory — 3 operation(s) for files.

GitHub OpenAPI

Operations 3

GET /api/projects/{project_id}/file-manifest Get the file manifest for a project #
GET /api/projects/{project_id}/file-content Stream file content from vector store by file path #
GET /api/projects/{project_id}/file-content/metadata Get file metadata from vector store #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/corestory:corestory-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

corestory-files-api-openapi.yml Raw ↑
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. It is designed for engineering, architecture, and product teams who need to extract business logic, technical specifications, architectural relationships, and system-level context from complex or legacy codebases. By interfacing directly with CoreStory API, users can:


    - Generate full Product Requirements Documents (PRDs) from a codebase

    - Extract detailed Technical Specifications for modernization or migration

    - Query a codebase using natural language to surface implementation details, logic paths, dependencies, and architectural insights

    - Construct and visualize knowledge graphs of systems, components, and relationships

    - Ingest, store, and retrieve content from a vector store for AI-powered retrieval-augmented generation (RAG) workflows


    CoreStory is especially valuable in contexts where:


    - Codebases are large, unstructured, or under-documented

    - Product and engineering teams are onboarding to unfamiliar systems

    - Technical stakeholders require visibility into system design or feature coverage

    - Modernization, replatforming, or M&A due diligence is underway


    The API can be integrated into existing CI/CD pipelines, internal developer portals, architecture review boards, product planning processes, or documentation automation workflows. All endpoints support secure authentication and are designed for high-availability, asynchronous workloads. Output formats include JSON, Markdown, and PDF, with flexible formatting options for downstream consumption. For step-by-step usage instructions and workflows, refer to the CoreStory API Quick Start Guide. ## Features


    * **Document Generation**

    * Generate complete Product Requirements Documents (PRD)

    * Generate Technical Specifications

    * Generate individual document sections (executive overview, user personas, etc.)

    * Format documents in JSON or Markdown


    * **Vector Store Management**

    * Ingest and manage documents in vector store

    * Query and retrieve document content

    * Manage document embeddings


    * **Context Management**

    * Manage context for different document types

    * Set and retrieve PRD context

    * Support for future context types (technical specs, user stories, etc.)


    * **Knowledge Graph**

    * Generate knowledge graphs from codebase queries

    * Visualize relationships between code entities

    * Analyze code structure and dependencies


    * **API Endpoints**

    * `/api/documents/*` - Document generation and formatting

    * `/api/generate/*` - Document formatting utilities

    * `/api/vector-store/*` - Vector store management

    * `/api/agents/*` - AI agent operations

    * `/api/context/*` - Context management for documents

    * `/api/graph/*` - Knowledge graph generation and analysis


    Note: JWT authentication support coming soon. All endpoints currently provide detailed OpenAPI documentation. * **Observability**

    * OpenTelemetry instrumentation for distributed tracing

    * Prometheus metrics endpoint at `/metrics`

    * Comprehensive request/response tracking

    * Custom business metrics


    # CoreStory System Architecture


    This document provides a high-level overview of how the CoreStory platform ingests, analyzes, and serves structured software intelligence through its API. The system is designed to process codebases and related technical artifacts in order to generate product specifications, technical documents, and knowledge graph representations. ---


    ## Core Components


    ### 1. **Ingestion Layer**


    - Accepts Git URLs, file uploads, or local archives

    - Extracts source files, documentation, and metadata

    - Initiates chunking and embedding via the vector store pipeline


    ### 2. **Vector Store and Context Engine**


    - Stores chunked and embedded documents

    - Supports semantic search and document retrieval

    - Feeds LLMs with scoped context for generation and reasoning


    ### 3.'
  version: 1.33.0
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: Files
paths:
  /api/projects/{project_id}/file-manifest:
    get:
      tags:
      - Files
      summary: Get the file manifest for a project
      description: Returns a manifest of files discovered during pre-ingestion analysis, each entry carrying why an excluded file was dropped or why an included file never reached the vector store. Defaults to included files only. Use status to ask for one kind directly, and page/size to page; without a size the whole manifest is returned.
      operationId: get_project_file_manifest
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - included
            - excluded
            - ingested
            - not_ingested
            type: string
          - type: 'null'
          description: Which files to return. 'not_ingested' is an included file no run recorded as landed, which includes files whose verdict was never written. Takes precedence over include_excluded and ingested_only
          title: Status
        description: Which files to return. 'not_ingested' is an included file no run recorded as landed, which includes files whose verdict was never written. Takes precedence over include_excluded and ingested_only
      - name: file_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Only return files whose path contains this text
          title: File Name
        description: Only return files whose path contains this text
      - 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:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Items per page. Omit for every file
          title: Size
        description: Items per page. Omit for every file
      - 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 a run recorded as landed in the vector store
          default: false
          title: Ingested Only
        description: Only return files a run recorded as landed in 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:
    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.
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Stable machine-readable code for clients that branch on the specific failure.
        required_organization:
          anyOf:
          - $ref: '#/components/schemas/RequiredOrganization'
          - type: 'null'
          description: Set when the caller can retry after switching organization context.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    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 reached the vector store
        exclusion_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Exclusion Reason
          description: Reason for exclusion, null for included files
        outcome:
          anyOf:
          - type: string
          - type: 'null'
          title: Outcome
          description: 'What the last ingestion run did with an included file that did not land: ''failed'' or ''skipped''. Null when the file landed, when it was excluded before ingestion, or when no run recorded it'
        outcome_stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Outcome Stage
          description: 'How far the file got before that outcome: ''extracted'', ''embedded'' or ''inserted'''
        outcome_detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Outcome Detail
          description: The reason recorded alongside that outcome
        blank:
          type: boolean
          title: Blank
          description: True for an included file that did not land because it is empty or whitespace-only, so there is nothing to index. Expected rather than a failure, whatever outcome the run recorded
          default: false
        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.
    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
    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.
    RequiredOrganization:
      properties:
        id:
          type: string
          title: Id
          description: Clerk organization id the client should switch to.
        name:
          type: string
          title: Name
          description: Display name of that organization.
      type: object
      required:
      - id
      - name
      title: RequiredOrganization
      description: The organization a caller must be acting under before a denied request can succeed.
    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)
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
          description: Direct link to the file in its source repository (with line range if specified)
        github_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Github Url
          description: Deprecated duplicate of source_url; kept for clients not yet regenerated
        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.
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    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.
    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.
    FileManifestResponse:
      properties:
        project_id:
          type: integer
          title: Project Id
          description: Project ID
        total_files:
          type: integer
          title: Total Files
          description: Files matching the status and name filters, before paging
        included_files:
          type: integer
          title: Included Files
          description: Matching files the pre-scan meant to ingest
        excluded_files:
          type: integer
          title: Excluded Files
          description: Matching files the pre-scan left out
        ingestion_status_degraded:
          type: boolean
          title: Ingestion Status Degraded
          description: True when the vector store lookup failed, so every entry's dates are absent
          default: false
        files:
          items:
            $ref: '#/components/schemas/FileManifestItem'
          type: array
          title: Files
          description: List of file manifest entries
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
          description: Paging metadata for this response
      type: object
      required:
      - project_id
      - total_files
      - included_files
      - excluded_files
      - files
      - pagination
      title: FileManifestResponse
      description: Complete file manifest for a project.
  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
  - git_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
x-provenance:
  method: harvested
  publisher: CoreStory
  source: https://c2s.corestory.ai/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)