CoreStory Subscriptions API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Subscriptions 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: Subscriptions
paths:
  /api/subscription/status:
    get:
      tags:
      - Subscriptions
      summary: Get Subscription Status
      description: Retrieve the current subscription status for the authenticated organization.
      operationId: get_subscription_status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/subscriptions/usage:
    get:
      tags:
      - Subscriptions
      summary: Get Usage Data
      description: 'Retrieve usage data for the current organization.


        Returns token consumption metrics, project count, and user count for the

        given period. ``period_start`` and ``period_end`` are required; omitting

        either fails fast with a 422.


        Authenticated via API key.'
      operationId: get_usage_data
      parameters:
      - name: period_start
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Period Start
      - name: period_end
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Period End
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageDataResponse'
        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
    SubscriptionProvider:
      type: string
      enum:
      - ms_marketplace
      - stripe
      title: SubscriptionProvider
      description: Subscription provider enum.
    UsageDataResponse:
      properties:
        period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
          description: Start of the usage period. Null when no date filter was applied.
        period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
          description: End of the usage period. Null when no date filter was applied.
        token_usage:
          type: integer
          title: Token Usage
          description: Total tokens consumed (input + output)
        input_tokens:
          type: integer
          title: Input Tokens
          description: Total input/prompt tokens consumed. Sentinel value -1 when the usage provider does not expose a prompt/completion split.
        output_tokens:
          type: integer
          title: Output Tokens
          description: Total output/completion tokens consumed. Sentinel value -1 when the usage provider does not expose a prompt/completion split.
        total_projects:
          type: integer
          title: Total Projects
          description: Number of projects in the organization
        total_users:
          type: integer
          title: Total Users
          description: Number of active users in the organization
        token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Token Cost
          description: Token cost in USD (if available)
        loc_consumed:
          type: integer
          title: Loc Consumed
          description: Total lines of code consumed across all ingestions (append-only; never decreases)
          default: 0
        loc_allowance:
          type: integer
          title: Loc Allowance
          description: Current lines-of-code allowance for the organization (the plan cap)
          default: 0
      type: object
      required:
      - token_usage
      - input_tokens
      - output_tokens
      - total_projects
      - total_users
      title: UsageDataResponse
      description: Response model for organization usage data.
    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
    SubscriptionStatusResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Subscription status: ''active'', ''suspended'', ''canceled'', or ''none'''
          examples:
          - active
          - suspended
          - canceled
          - none
        plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id
          description: Plan identifier (e.g., 'enterprise-monthly')
        provider:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionProvider'
          - type: 'null'
          description: Subscription provider
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Timestamp when subscription was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Timestamp when subscription was last updated
        current_period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period Start
          description: Start of the current billing period
        current_period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period End
          description: End of the current billing period (renewal date)
        price_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Id
          description: Stripe Price ID for the active plan
        unit_amount:
          anyOf:
          - type: integer
          - type: 'null'
          title: Unit Amount
          description: Price per unit in the smallest currency unit (e.g. cents for USD)
        quantity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Quantity
          description: Number of units subscribed
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: Three-letter ISO currency code (e.g. 'usd')
        interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Interval
          description: Billing interval from the price (e.g. 'month', 'year')
        cancel_at_period_end:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Cancel At Period End
          description: Stripe's cancel_at_period_end flag for the subscription
        cancel_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cancel At
          description: Timestamp when the subscription is scheduled to cancel, if any
        canceled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Canceled At
          description: Timestamp when the cancellation was requested, if any
      type: object
      required:
      - status
      title: SubscriptionStatusResponse
      description: Response model for organization subscription status.
  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)