CoreStory Prompts API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Prompts 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: Prompts
paths:
  /api/prompts/{project_id}/prd/{prd_id}:
    get:
      tags:
      - Prompts
      summary: Get custom prompts
      description: Retrieve all custom prompts for PRD, or a specific prompt if step is provided
      operationId: get_project_prompts
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: prd_id
        in: path
        required: true
        schema:
          type: integer
          title: Prd Id
      - name: step
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AllPRDStepsEnum'
          - type: 'null'
          description: Optional step to filter by specific prompt
          title: Step
        description: Optional step to filter by specific prompt
      responses:
        '200':
          description: List of custom prompts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Prompt not found
        '500':
          description: Internal server error
  /api/prompts/{project_id}/prd/{prd_id}/{prompt_id}:
    get:
      tags:
      - Prompts
      summary: Get a custom prompt by ID
      description: Retrieve a specific custom prompt by its ID
      operationId: get_project_prompt
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: prd_id
        in: path
        required: true
        schema:
          type: integer
          title: Prd Id
      - name: prompt_id
        in: path
        required: true
        schema:
          type: integer
          title: Prompt Id
      responses:
        '200':
          description: The requested custom prompt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Prompt not found
        '500':
          description: Internal server error
  /api/prompts/list:
    get:
      tags:
      - Prompts
      summary: Get all custom prompts across all PRDs
      description: Retrieve all custom prompts from all PRDs with pagination
      operationId: list_prompts
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of items per page
          default: 100
          title: Limit
        description: Number of items per page
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of items to skip
          default: 0
          title: Offset
        description: Number of items to skip
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search query for prompt content and step name
          title: Q
        description: Search query for prompt content and step name
      - name: prd_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by PRD ID
          title: Prd Id
        description: Filter by PRD ID
      responses:
        '200':
          description: Paginated list of all custom prompts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPromptListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Prompt not found
        '500':
          description: Internal server error
  /api/prompts/{prompt_id}:
    get:
      tags:
      - Prompts
      summary: Get a custom prompt by ID
      description: Retrieve a specific custom prompt by its ID
      operationId: get_prompt
      parameters:
      - name: prompt_id
        in: path
        required: true
        schema:
          type: integer
          title: Prompt Id
      responses:
        '200':
          description: The requested custom prompt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Prompt not found
        '500':
          description: Internal server error
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
    PromptResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Unique identifier for the prompt
        step:
          type: string
          title: Step
          description: Name or identifier of the step (see AllPRDStepsEnum for valid values)
        prompt:
          type: string
          title: Prompt
          description: The custom prompt text
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the prompt was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: When the prompt was last updated
        prd_id:
          type: integer
          title: Prd Id
          description: ID of the PRD this prompt belongs to
          default: 1
        replacement:
          type: boolean
          title: Replacement
          description: Whether this prompt replaces the default prompt
          default: false
      type: object
      required:
      - id
      - step
      - prompt
      - created_at
      - updated_at
      title: PromptResponse
      description: Response model for a single prompt
      example:
        created_at: '2025-01-01T00:00:00'
        id: 1
        prd_id: 1
        prompt: Custom prompt text here
        replacement: false
        step: user_stories
        updated_at: '2025-01-01T00:00:00'
    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.
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    PromptListResponse:
      properties:
        prompts:
          items:
            $ref: '#/components/schemas/PromptResponse'
          type: array
          title: Prompts
          description: List of prompts
        available_steps:
          items:
            type: string
          type: array
          title: Available Steps
          description: List of available step values
      type: object
      required:
      - prompts
      title: PromptListResponse
      description: Response model for a list of prompts
    AllPRDStepsEnum:
      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
      - retriever_api_specification
      - retriever_interface_specification
      - retriever_data_models
      - retriever_classes
      - retriever_summary
      title: AllPRDStepsEnum
    PaginatedPromptListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PromptResponse'
          type: array
          title: Results
        count:
          type: integer
          title: Count
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - results
      - count
      - limit
      - offset
      title: PaginatedPromptListResponse
  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)