CoreStory User API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation User 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: User
paths:
  /api/user/activity-stats:
    get:
      tags:
      - User
      summary: Get user activity statistics
      description: Retrieve activity statistics for the currently authenticated user
      operationId: get_user_activity_stats
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserActivityStatsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/user/recent-conversations:
    get:
      tags:
      - User
      summary: Get recent conversations
      description: Retrieve a list of recent conversations for the currently authenticated user
      operationId: get_recent_conversations
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: 'Number of recent conversations to retrieve (default: 10, max: 50)'
          default: 10
          title: Limit
        description: 'Number of recent conversations to retrieve (default: 10, max: 50)'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentConversationsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/user/onboarding-profile:
    get:
      tags:
      - User
      summary: Get user onboarding profile
      description: Retrieve the onboarding profile for the currently authenticated user
      operationId: get_user_onboarding_profile
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOnboardingProfileResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    put:
      tags:
      - User
      summary: Upsert user onboarding profile
      description: Create or update the onboarding profile for the currently authenticated user (idempotent).
      operationId: upsert_user_onboarding_profile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserOnboardingProfileUpsertRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOnboardingProfileResponse'
        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
    RecentConversationsResponse:
      properties:
        conversations:
          items:
            $ref: '#/components/schemas/RecentConversationItem'
          type: array
          title: Conversations
          description: List of recent conversations with their details
      type: object
      required:
      - conversations
      title: RecentConversationsResponse
      description: Response schema for recent conversations
    UserOnboardingProfileResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the onboarding profile
        user_id:
          type: string
          title: User Id
          description: ID of the user this profile belongs to
        organization_id:
          type: string
          title: Organization Id
          description: ID of the organization this profile is scoped to
        role:
          type: string
          title: Role
          description: User's professional role (e.g. developer, product_manager)
        goals:
          items:
            type: string
          type: array
          title: Goals
          description: List of user's onboarding goals
        path_type:
          type: string
          title: Path Type
          description: Preferred onboarding workflow path (e.g. ide_first, docs_first)
        preferences:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Preferences
          description: Flexible JSONB bucket for user preferences
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When onboarding was completed or skipped, or null
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the profile was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the profile was last updated
      type: object
      required:
      - id
      - user_id
      - organization_id
      - role
      - goals
      - path_type
      - created_at
      - updated_at
      title: UserOnboardingProfileResponse
      description: Response schema for user onboarding profile retrieval.
      example:
        created_at: '2026-01-01T00:00:00Z'
        goals:
        - improve_code_quality
        - speed_up_reviews
        id: 550e8400-e29b-41d4-a716-446655440000
        organization_id: 550e8400-e29b-41d4-a716-446655440002
        path_type: ide_first
        role: developer
        updated_at: '2026-01-01T00:00:00Z'
        user_id: 550e8400-e29b-41d4-a716-446655440001
    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.
    UserActivityStatsResponse:
      properties:
        total_codebases:
          type: integer
          title: Total Codebases
          description: Total number of projects (codebases) created or accessible to the user
        total_conversations:
          type: integer
          title: Total Conversations
          description: Total number of conversations across all of the user's projects
      type: object
      required:
      - total_codebases
      - total_conversations
      title: UserActivityStatsResponse
      description: User's activity statistics
      example:
        total_codebases: 5
        total_conversations: 12
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    OnboardingPathType:
      type: string
      enum:
      - ide_first
      - docs_first
      title: OnboardingPathType
      description: User's preferred onboarding workflow path.
    UserOnboardingProfileUpsertRequest:
      properties:
        role:
          $ref: '#/components/schemas/UserRole'
          description: User's professional role
        goals:
          items:
            type: string
          type: array
          title: Goals
          description: List of user's onboarding goals
        path_type:
          $ref: '#/components/schemas/OnboardingPathType'
          description: Preferred onboarding workflow path
        preferences:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Preferences
          description: Flexible JSONB bucket for user preferences
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When onboarding was completed or skipped
      type: object
      required:
      - role
      - goals
      - path_type
      title: UserOnboardingProfileUpsertRequest
      description: 'Request schema for the idempotent PUT upsert endpoint.


        role, goals, and path_type are required (needed for creation).

        preferences and completed_at are optional.'
    RecentConversationItem:
      properties:
        id:
          type: integer
          title: Id
          description: Conversation ID
        title:
          type: string
          title: Title
          description: Conversation title
        project_id:
          type: integer
          title: Project Id
          description: ID of the project the conversation belongs to
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
          description: Name of the project the conversation belongs to
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Conversation creation timestamp
      type: object
      required:
      - id
      - title
      - project_id
      - created_at
      title: RecentConversationItem
      description: A single recent conversation entry.
    UserRole:
      type: string
      enum:
      - developer
      - engineering_manager
      - architect
      - business_analyst
      - product_manager
      - compliance_audit
      title: UserRole
      description: User's professional role for onboarding profile.
  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)