CoreStory Files API
The files API from CoreStory — 3 operation(s) for files.
The files API from CoreStory — 3 operation(s) for files.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/corestory:corestory-files-api"
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.
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: 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)