CoreStory Documents API

The documents API from CoreStory — 1 operation(s) for documents.

GitHub OpenAPI

Operations 3

POST /api/documents/{project_id}/sections/features/requirements Generate technical requirements based on user stories #
POST /api/documents Request a document generated from a set of projects #
GET /api/documents List the documents you can see #

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-documents-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-documents-api-openapi.yml Raw ↑
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)