CoreStory Sections API
The sections API from CoreStory — 7 operation(s) for sections.
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/corestory:corestory-sections-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
openapi: 3.2.0
info:
title: Crowdbotics API Documentation Sections 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: Sections
paths:
/api/projects/{project_id}/sections/{section_name}/generate:
post:
tags:
- Sections
summary: Generate a specific section
description: Generate (or regenerate) a single section.
operationId: generate_section
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: section_name
in: path
required: true
schema:
$ref: '#/components/schemas/DocumentSectionsDashedEnum'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GeneratePRDSectionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
title: Response Generate Section
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections/generate-all:
post:
tags:
- Sections
summary: Generate all sections (PRD + Tech Spec) in background
description: 'Generate all PRD and tech-spec sections on the queue worker.
Used for "living PRD" — after reingestion, regenerate everything.'
operationId: generate_all_sections
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateAllRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Generate All Sections
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections/tech-user-stories/catalog:
get:
tags:
- Sections
summary: Get a catalog of tech-user-story facets for UI browsing
description: Return unique, alpha-sorted catalog lists for main_features, epics, and personas.
operationId: get_tech_user_stories_section_catalog
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Tech User Stories Section Catalog
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections/user-stories/catalog:
get:
tags:
- Sections
summary: Get a catalog of user-story facets for UI browsing
description: Return unique, alpha-sorted catalog lists for main_features, epics, and personas.
operationId: get_user_stories_section_catalog
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get User Stories Section Catalog
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections/availability:
get:
tags:
- Sections
summary: Report which sections have content, without their payloads
description: Report which sections have content for the resolved PRD version.
operationId: get_sections_availability
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SectionsAvailabilityResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections:
get:
tags:
- Sections
summary: Get all sections (PRD + Tech Spec) for the project
description: Get all PRD + tech-spec sections combined into a single response.
operationId: get_all_sections
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AllSectionsResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/projects/{project_id}/sections/{section_name}:
get:
tags:
- Sections
summary: Get a single section by name
description: Get a single section (PRD or tech-spec) with optional pagination and filtering.
operationId: get_section
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: section_name
in: path
required: true
schema:
$ref: '#/components/schemas/DocumentSectionsDashedEnum'
- name: version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Version
- name: epics
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Epic IDs
title: Epics
description: Epic IDs
- name: personas
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Persona IDs
title: Personas
description: Persona IDs
- name: main_features
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Main feature IDs
title: Main Features
description: Main feature IDs
- name: keywords
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Keyword list
title: Keywords
description: Keyword list
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Free-text; supports exact, "a or b", or "a and b"
title: Search
description: Free-text; supports exact, "a or b", or "a and b"
- 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:
type: integer
maximum: 10000
minimum: 1
description: 'Items per page (default: 10000)'
default: 10000
title: Size
description: 'Items per page (default: 10000)'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SectionResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
patch:
tags:
- Sections
summary: Update a section
description: Update a single section (PRD or tech-spec).
operationId: update_section
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: section_name
in: path
required: true
schema:
$ref: '#/components/schemas/DocumentSectionsDashedEnum'
- name: version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Version
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
title: Patch Data
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BasicSuccessResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
/api/sections/catalog:
get:
tags:
- Sections
summary: List all document section names (PRD + Tech Spec)
description: Return the static catalog of all 14 PRD + Tech Spec section names.
operationId: get_section_catalog
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties:
items:
additionalProperties:
type: string
type: object
type: array
type: object
title: Response Get Section Catalog
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
LanguageInfo:
properties:
code:
type: string
title: Code
description: BCP-47 language code (ja, es, fr-CA).
name:
type: string
title: Name
description: Language name in its native script (English, français (Canada)).
type: object
required:
- code
- name
title: LanguageInfo
description: Language information with code and native display name.
SpecFormat:
type: string
enum:
- legacy
- dga
- spec_v2
title: SpecFormat
description: 'Self-documenting label for the format a generated spec is in.
On responses it is derived from ``content_version`` so the viewer (and any
API consumer) renders the right experience without guessing from which
fields happen to be present. On ingestion requests the same values pick
which generation pipeline runs.'
GeneratePRDSectionRequest:
properties:
custom_prompt:
anyOf:
- $ref: '#/components/schemas/PRDCustomPromptRequest'
- type: 'null'
language:
anyOf:
- type: string
- type: 'null'
title: Language
type: object
title: GeneratePRDSectionRequest
PRDCustomPromptRequest:
properties:
prompt:
type: string
title: Prompt
replacement:
type: boolean
title: Replacement
type: object
required:
- prompt
- replacement
title: PRDCustomPromptRequest
BasicSuccessResponse:
properties:
detail:
type: string
title: Detail
default: success
type: object
title: BasicSuccessResponse
description: 'Use this for returns for deletes and patches.
UI ALWAYS needs some payload return. This just standarizes it.'
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
SectionsAvailabilityResponse:
properties:
prd_version_uid:
type: string
title: Prd Version Uid
description: UID of the version the summary was computed from.
sections:
additionalProperties:
type: boolean
type: object
title: Sections
description: Dashed section name to whether the section has content.
type: object
required:
- prd_version_uid
- sections
title: SectionsAvailabilityResponse
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.
SectionResponse:
properties:
prd_id:
type: integer
title: Prd Id
created_at:
type: string
format: date-time
title: Created At
section_name:
type: string
title: Section Name
description: Dashed section name, e.g. 'executive-overview'.
content:
title: Content
description: The section content. Shape varies by section.
content_version:
type: integer
title: Content Version
description: 1=legacy, 2=DGA-generated, 3=Spec V2.
default: 1
can_regenerate:
type: boolean
title: Can Regenerate
default: false
custom_prompt:
anyOf:
- type: string
- type: 'null'
title: Custom Prompt
filter_stats:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter Stats
description: Filtering counts, e.g. total vs filtered user stories. Only populated for filterable sections.
prd_version_num:
anyOf:
- type: integer
- type: 'null'
title: Prd Version Num
prd_version_uid:
anyOf:
- type: string
- type: 'null'
title: Prd Version Uid
language:
anyOf:
- $ref: '#/components/schemas/LanguageInfo'
- type: 'null'
description: Language the section was generated in, if non-English.
pagination:
anyOf:
- $ref: '#/components/schemas/PaginationMeta'
- type: 'null'
format_label:
$ref: '#/components/schemas/SpecFormat'
description: 'Self-documenting format label derived from content_version: legacy / dga / spec_v2.'
readOnly: true
type: object
required:
- prd_id
- created_at
- section_name
- format_label
title: SectionResponse
description: 'Single-section response for GET /sections/{section_name}.
Content is always in the `content` field regardless of which section was
requested. The `section_name` field identifies the section in dashed form
(e.g. ''executive-overview'').'
ErrorSchema:
properties:
error:
$ref: '#/components/schemas/ErrorBody'
type: object
required:
- error
title: ErrorSchema
GenerateAllRequest:
properties:
language:
anyOf:
- type: string
- type: 'null'
title: Language
type: object
title: GenerateAllRequest
AllSectionsResponse:
properties:
system_architecture:
anyOf:
- additionalProperties: true
type: object
- type: string
title: System Architecture
description: System architecture details
data_models:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Data Models
description: Data models details
user_interface:
anyOf:
- additionalProperties: true
type: object
- type: string
title: User Interface
description: User interface details
api_specifications:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Api Specifications
description: API specifications details
interface_specifications:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Interface Specifications
description: Interface specifications details
integration_points:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Integration Points
description: Integration points details
security_considerations:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Security Considerations
description: Security considerations details
implementation_strategy:
anyOf:
- additionalProperties: true
type: object
- type: string
title: Implementation Strategy
description: Implementation strategy details
tech_user_stories:
anyOf:
- items: {}
type: array
- type: string
title: Tech User Stories
description: User stories details
caveats:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Caveats
description: Per-section provenance caveats keyed by section name. Only populated for sections whose evidence is documentation-only or mixed; absent when all sections are grounded in code or have no sources.
executive_overview:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Executive Overview
description: Executive overview details
user_personas:
additionalProperties: true
type: object
title: User Personas
description: User personas details
high_level_requirements:
additionalProperties: true
type: object
title: High Level Requirements
description: High level requirements details
user_stories:
anyOf:
- items: {}
type: array
- type: string
title: User Stories
description: User stories details
security_requirements:
additionalProperties: true
type: object
title: Security Requirements
description: Security requirements details
prd_id:
type: integer
title: Prd Id
prd_version_num:
anyOf:
- type: integer
- type: 'null'
title: Prd Version Num
prd_version_uid:
anyOf:
- type: string
- type: 'null'
title: Prd Version Uid
generated_from_commit_sha:
anyOf:
- type: string
- type: 'null'
title: Generated From Commit Sha
custom_prompt:
anyOf:
- type: string
- type: 'null'
title: Custom Prompt
title:
anyOf:
- type: string
- type: 'null'
title: Title
created_at:
type: string
format: date-time
title: Created At
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
metadata:
additionalProperties: true
type: object
title: Metadata
description: Job metadata including version and version_tag
type: object
required:
- prd_id
- created_at
title: AllSectionsResponse
description: Combined PRD + Tech-Spec sections response for unified /sections/ endpoint.
DocumentSectionsDashedEnum:
type: string
enum:
- executive-overview
- user-personas
- high-level-requirements
- user-stories
- security-requirements
- system-architecture
- data-models
- user-interface
- api-specifications
- interface-specifications
- integration-points
- security-considerations
- tech-user-stories
- implementation-strategy
title: DocumentSectionsDashedEnum
description: PRD + tech-spec sections only (no retriever). Use for user-facing endpoints.
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)