Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Crowdbotics API Documentation Documents 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: Documents
paths:
/api/documents/{project_id}/sections/features/requirements:
post:
tags:
- Documents
summary: Generate technical requirements based on user stories
description: 'Generate technical requirements based on user stories.
Args:
project_id: The project ID for which to generate technical requirements
user_stories: List of user stories to generate requirements from
user: The authenticated user
org_id: The organization ID from the header
Returns:
Any: The generated technical requirements
Raises:
HTTPException: If generation fails'
operationId: generate_tech_requirements
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
title: User Stories
responses:
'200':
description: Successful Response
content:
application/json:
schema:
title: Response Generate Tech Requirements
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
'500':
description: Internal server error
/api/documents:
post:
tags:
- Documents
summary: Request a document generated from a set of projects
description: 'Queues a document read across every project given and returns it at once, before it exists, so it can be polled. The set is fixed when the document is requested: covering a different set means requesting another document.'
operationId: request_document_across_projects
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentAcrossProjectsRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentMetadataSummary'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
'404':
description: A project was not found in this organization
'422':
description: Invalid request
'424':
description: Background worker unavailable; the request can be retried
get:
tags:
- Documents
summary: List the documents you can see
description: The organization's custom documents, each saying which projects it was generated from. Give a project to narrow the list to the documents covering it, shared ones included.
operationId: list_documents_across_projects
parameters:
- name: project_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Only documents covering this project.
title: Project Id
description: Only documents covering this project.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
description: How many to return.
default: 100
title: Limit
description: How many to return.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: How many to skip.
default: 0
title: Offset
description: How many to skip.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDocumentListResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
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
JobStatus:
type: string
enum:
- not_started
- running
- completed
- failed
- cancelled
title: JobStatus
description: Job status enumeration
SectionDefinition-Input:
properties:
name:
type: string
title: Name
description: Section heading/title
level:
type: integer
maximum: 6.0
minimum: 1.0
title: Level
description: Heading level (1-6)
default: 2
description:
type: string
title: Description
description: Context for intent derivation. Describes what this section should cover.
default: ''
queries:
items:
anyOf:
- type: string
- $ref: '#/components/schemas/QueryItem'
type: array
title: Queries
description: Research queries for this section.
depends_on:
items:
type: string
type: array
title: Depends On
description: Section names that must be generated before this section. Their output will be available as context during generation.
dependency_context_mode:
type: string
enum:
- full
- summary
title: Dependency Context Mode
description: 'How to include dependency content: ''full'' (the whole section, subsections included) or ''summary'' (cut to 500 characters, subsections listed by name).'
default: summary
instructions:
type: string
title: Instructions
description: 'Section-specific instructions. Combined with global instructions to guide content generation. Example: ''Keep brief'' or ''Include code examples''.'
default: ''
derive_from_context:
type: boolean
title: Derive From Context
description: If True, skip codebase research and generate content purely from dependency context and instructions. Use for synthesis sections like 'User Stories from Requirements'.
default: false
role:
anyOf:
- type: string
enum:
- descriptive
- evaluative
- prescriptive
- type: 'null'
title: Role
description: What the section does with the codebase. 'descriptive' reports what the code does (architecture, components); 'evaluative' judges it against the request (risks, constraints); 'prescriptive' states what the result must do (acceptance criteria, scope). Evaluative and prescriptive sections keep the user's stated requirements instead of replacing them with current behavior, each with the code's current status. Classified from the section when omitted.
polish:
anyOf:
- type: boolean
- type: 'null'
title: Polish
description: Whether to polish this section. None = inherit from global setting. True = always polish. False = skip polishing.
polish_instructions:
type: string
title: Polish Instructions
description: Section-specific polish instructions. Combined with global polish_instructions.
default: ''
output_schema:
anyOf:
- {}
- type: 'null'
title: Output Schema
description: Pydantic model for LLM structured output. When set, the section generator uses structured-output mode and the result is stored as JSON in PRDStep.content. Set programmatically on preset definitions; not serializable to/from JSON.
subsections:
items:
$ref: '#/components/schemas/SectionDefinition-Input'
type: array
title: Subsections
description: Nested subsections. These are generated recursively.
research_strategy:
type: string
enum:
- legacy
- react_per_feature
title: Research Strategy
description: Which generation pipeline to use for this section. 'legacy' keeps the orchestrator-based research path; 'react_per_feature' delegates to PerFeatureUserStoryGenerator and requires upstream feature extraction.
default: legacy
requires_signal:
anyOf:
- type: string
- type: 'null'
title: Requires Signal
description: Applicability signal that must be present for this section to be generated. When set and absent, the section is omitted entirely rather than generated empty.
additionalProperties: false
type: object
required:
- name
title: SectionDefinition
description: "Complete section definition for document generation.\n\nCombines section identity (name, level) with generation configuration\n(queries, depends_on, etc.) in a single model. This is the only section\nmodel used throughout the pipeline.\n\nExample:\n SectionDefinition(\n name=\"User Stories\",\n level=2,\n description=\"User stories derived from requirements\",\n depends_on=[\"Requirements\"],\n derive_from_context=True,\n instructions=\"Generate user stories in standard format with acceptance criteria.\",\n subsections=[\n SectionDefinition(\n name=\"Authentication Stories\",\n queries=[\"What authentication user stories can be derived?\"],\n ),\n SectionDefinition(\n name=\"Payment Stories\",\n queries=[\"What payment user stories can be derived?\"],\n ),\n ],\n )"
TemplateStyle:
properties:
tone:
type: string
enum:
- formal
- technical
- casual
- mixed
title: Tone
default: technical
uses_tables:
type: boolean
title: Uses Tables
default: false
uses_diagrams:
type: boolean
title: Uses Diagrams
default: false
uses_code_blocks:
type: boolean
title: Uses Code Blocks
default: false
uses_bullet_lists:
type: boolean
title: Uses Bullet Lists
default: true
uses_numbered_lists:
type: boolean
title: Uses Numbered Lists
default: false
heading_style:
type: string
enum:
- title_case
- sentence_case
- uppercase
title: Heading Style
default: title_case
section_numbering:
type: boolean
title: Section Numbering
default: false
estimated_detail_level:
type: string
enum:
- brief
- standard
- detailed
title: Estimated Detail Level
default: standard
type: object
title: TemplateStyle
description: Writing style characteristics extracted from template.
DocumentOptions:
properties:
include_code_examples:
type: boolean
title: Include Code Examples
description: Include code snippets where relevant
default: true
include_diagrams:
type: boolean
title: Include Diagrams
description: Generate Mermaid diagrams
default: true
include_business_rules:
type: boolean
title: Include Business Rules
description: Include business rules section
default: true
include_source_references:
type: boolean
title: Include Source References
description: Include references to source files
default: true
detail_level:
type: string
enum:
- brief
- standard
- detailed
title: Detail Level
description: Level of detail in generated content
default: standard
output_format:
type: string
enum:
- markdown
- html
- pdf
title: Output Format
description: Output format
default: markdown
max_tokens_per_section:
type: integer
maximum: 10000.0
minimum: 500.0
title: Max Tokens Per Section
description: Approximate max tokens per section
default: 2000
polish:
type: boolean
title: Polish
description: Whether to polish sections. Each section is polished individually after generation. Per-section polish settings in SectionDefinition can override this.
default: true
polish_instructions:
type: string
title: Polish Instructions
description: Custom instructions for the polishing step (e.g., 'relate user stories to functional requirements')
default: ''
reference_validation:
type: string
enum:
- hybrid
- llm
- none
title: Reference Validation
description: 'Post-generation reference validation mode. ''hybrid'' (default): regex structural checks + semantic LLM validation for compliance claims, personas, packages, data models, and unformatted file paths, followed by a single LLM correction call if issues are found. ''llm'': legacy LLM extraction-only mode — extracts all references via structured LLM call and cross-checks against the manifest. ''none'': skip post-generation validation.'
default: hybrid
additionalProperties: false
type: object
title: DocumentOptions
description: Options for document generation.
app__documents__schemas__DocumentType:
type: string
enum:
- project_specification
- technical_specification
- spec_v2
- api_documentation
- architecture_document
- user_guide
- custom
title: DocumentType
description: Known document types with specialized handling.
DocumentAcrossProjectsRequest:
properties:
project_ids:
items:
type: integer
type: array
minItems: 1
title: Project Ids
description: The projects the document is generated from. The first is the one it is stored under.
generation_request:
$ref: '#/components/schemas/DocumentGenerationRequest-Input'
type: object
required:
- project_ids
- generation_request
title: DocumentAcrossProjectsRequest
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.
ProjectIngestionInfo:
properties:
status:
$ref: '#/components/schemas/JobStatus'
description: Current ingestion status
default: not_started
sync_status:
$ref: '#/components/schemas/ProjectSyncStatus'
description: Derived sync-status badge, matching the org roster and pinned-workspaces surfaces. Unlike `status` (the raw latest ingestion job state), this reflects whether the most recent ingestion actually failed, is in-flight, stale, or up to date.
default: up_to_date
failure_type:
anyOf:
- type: string
- type: 'null'
title: Failure Type
description: Short categorical failure tag of the most recent ingestion, set only when `sync_status` is `failed`. Lets the UI render category-specific guidance. See `app.orchestrations.ingestion.failure_handler.classify_failure` for the value set.
failure_reason:
anyOf:
- type: string
- type: 'null'
title: Failure Reason
description: Human-readable failure detail, set only when `sync_status` is `failed`.
progress:
anyOf:
- type: number
- type: 'null'
title: Progress
description: Ingestion progress percentage
is_stale:
type: boolean
title: Is Stale
description: Whether the intelligence is out of sync with the repo
default: false
file_count:
anyOf:
- type: integer
- type: 'null'
title: File Count
description: Number of files ingested into vector store
last_ingested_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Ingested At
description: Timestamp of last successful ingestion
commit_sha:
anyOf:
- type: string
- type: 'null'
title: Commit Sha
description: Git commit SHA of the last successful ingestion
stale_since_sha:
anyOf:
- type: string
- type: 'null'
title: Stale Since Sha
description: Remote commit SHA that triggered staleness
created_by:
anyOf:
- type: string
- type: 'null'
title: Created By
description: User ID who triggered the last ingestion
type: object
title: ProjectIngestionInfo
description: Grouped ingestion state for a project.
ProjectSyncStatus:
type: string
enum:
- up_to_date
- updating
- stale
- failed
- couldnt_process
title: ProjectSyncStatus
description: 'Derived sync/processing status for a project, shared across the org roster,
pinned-workspaces, and project detail/list surfaces.'
ErrorSchema:
properties:
error:
$ref: '#/components/schemas/ErrorBody'
type: object
required:
- error
title: ErrorSchema
QueryItem:
properties:
topic:
type: string
title: Topic
description: The research query/question
type: object
required:
- topic
title: QueryItem
description: A research query.
DocumentMetadataSummary:
properties:
id:
type: string
title: Id
title:
type: string
title: Title
document_type:
type: string
title: Document Type
origin:
$ref: '#/components/schemas/DocumentOrigin'
generated_at:
type: string
format: date-time
title: Generated At
description: When the document was generated, or requested if it is not ready
project_id:
type: integer
title: Project Id
description: The project the document is recorded under, the first of its set
project_ids:
items:
type: integer
type: array
title: Project Ids
description: Every project the document was generated from
section_count:
type: integer
title: Section Count
description: Sections in the document, or in the requested outline
status:
$ref: '#/components/schemas/DocumentStatus'
default: ready
progress:
type: number
maximum: 100.0
minimum: 0.0
title: Progress
description: Percentage complete
default: 100.0
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Why generation failed
ingestion:
anyOf:
- $ref: '#/components/schemas/ProjectIngestionInfo'
- type: 'null'
description: The least fresh of the projects it covers, since a section drawn from a stale one is stale. Set on the organization-wide listing only.
type: object
required:
- id
- title
- document_type
- origin
- generated_at
- project_id
- section_count
title: DocumentMetadataSummary
description: 'Summary metadata for listing documents.
The lifecycle fields default to READY, which everything in storage is.'
DocumentStatus:
type: string
enum:
- generating
- ready
- failed
title: DocumentStatus
description: Lifecycle of a document. Only a READY one has content and sections.
DocumentGenerationRequest-Input:
properties:
document_type:
$ref: '#/components/schemas/app__documents__schemas__DocumentType'
description: Type of document to generate
default: project_specification
section_definitions:
items:
$ref: '#/components/schemas/SectionDefinition-Input'
type: array
title: Section Definitions
description: Explicit section definitions. Sections are generated in the order specified.
style:
anyOf:
- $ref: '#/components/schemas/TemplateStyle'
- type: 'null'
description: Writing style. If not provided, uses sensible defaults based on document_type.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Document title. May contain '{project_name}', which is interpolated at assembly time.
origin:
$ref: '#/components/schemas/DocumentOrigin'
description: 'Server-controlled. Ignored on input: requests reaching the API or the MCP tools are forced to ''custom'', and only the built-in spec builders set ''default''.'
default: custom
instructions:
type: string
title: Instructions
description: Custom instructions (focus areas, exclusions, etc.)
default: ''
global_queries:
items:
type: string
type: array
title: Global Queries
description: Queries to run for all sections (e.g., 'What is the purpose of this system?')
auto_research:
type: boolean
title: Auto Research
description: Auto-generate relevant queries for each section based on its content type
default: true
questions:
items:
type: string
type: array
title: Questions
description: (Deprecated) Use global_queries instead. Questions applied to all sections.
options:
$ref: '#/components/schemas/DocumentOptions'
description: Generation options
additionalProperties: false
type: object
required:
- section_definitions
title: DocumentGenerationRequest
description: "Request to generate a dynamic document.\n\nProvide `section_definitions` for full control over document structure,\nalong with optional `style`, `title`, and `instructions`.\n\nExample:\n DocumentGenerationRequest(\n title=\"MyApp Technical Specification\",\n document_type=DocumentType.TECH_SPEC,\n style=TemplateStyle(tone=\"formal\", uses_tables=True),\n section_definitions=[\n SectionDefinition(name=\"Overview\", level=2, queries=[\"What does the system do?\"]),\n SectionDefinition(name=\"Architecture\", level=2, depends_on=[\"Overview\"]),\n ],\n )"
DocumentOrigin:
type: string
enum:
- default
- custom
title: DocumentOrigin
description: 'Which pipeline produced a generated document.
DEFAULT is the project''s built-in spec, served through the sections
endpoints; CUSTOM is served through the documents endpoints.'
PaginatedDocumentListResponse:
properties:
results:
items:
$ref: '#/components/schemas/DocumentMetadataSummary'
type: array
title: Results
count:
type: integer
title: Count
description: How many match, ignoring the page.
limit:
type: integer
title: Limit
offset:
type: integer
title: Offset
type: object
required:
- results
- count
- limit
- offset
title: PaginatedDocumentListResponse
description: A page of documents, each saying which projects it covers.
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)