CoreStory Github Integration API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Github Integration 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: GitHub integration
paths:
  /api/github/installations/start:
    post:
      tags:
      - GitHub integration
      summary: Start GitHub App installation
      description: Generate a GitHub App installation URL for the authenticated user. The URL includes embedded user context for callback association.
      operationId: start_github_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartInstallationResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/callback:
    get:
      tags:
      - GitHub integration
      summary: Handle GitHub App installation callback
      description: Callback endpoint invoked by GitHub after app installation. Handles install, update, and pending approval flows.
      operationId: github_installation_callback
      parameters:
      - name: installation_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: GitHub installation ID
          title: Installation Id
        description: GitHub installation ID
      - name: setup_action
        in: query
        required: true
        schema:
          type: string
          description: Setup action (install/update/request)
          title: Setup Action
        description: Setup action (install/update/request)
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: State parameter for user association
          title: State
        description: State parameter for user association
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Github Installation Callback
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/{installation_id}:
    delete:
      tags:
      - GitHub integration
      summary: Remove GitHub installation
      description: Disconnect a GitHub App installation from the current organization. Uninstalls from GitHub only when no other organization is still using the installation.
      operationId: remove_github_installation
      parameters:
      - name: installation_id
        in: path
        required: true
        schema:
          type: integer
          title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveInstallationResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations:
    get:
      tags:
      - GitHub integration
      summary: List GitHub installations
      description: List GitHub App installations accessible to the current user, including organization and personal installations.
      operationId: list_github_installations
      parameters:
      - name: include_personal
        in: query
        required: false
        schema:
          type: boolean
          description: Include personal GitHub User installations
          default: true
          title: Include Personal
        description: Include personal GitHub User installations
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedInstallationResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/summary:
    get:
      tags:
      - GitHub integration
      summary: Get installations summary
      description: Get a summary of GitHub installations with counts and access breakdown by type.
      operationId: get_github_installations_summary
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/{installation_id}/alias:
    post:
      tags:
      - GitHub integration
      summary: Update installation alias
      description: Update the display alias for a GitHub installation.
      operationId: update_github_installation_alias
      parameters:
      - name: installation_id
        in: path
        required: true
        schema:
          type: integer
          title: Installation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              minLength: 1
              maxLength: 255
              title: Alias
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/{installation_id}/repos:
    get:
      tags:
      - GitHub integration
      summary: List GitHub repositories
      description: List repositories accessible through a GitHub App installation with pagination.
      operationId: list_github_repositories
      parameters:
      - name: installation_id
        in: path
        required: true
        schema:
          type: integer
          title: Installation Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReposListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/installations/{installation_id}/repo-branches:
    get:
      tags:
      - GitHub integration
      summary: List repository branches
      description: List branches for a specific repository with pagination support. When `search` is provided, `page` and `limit` are ignored and all matching branches are returned as a single result set.
      operationId: list_github_branches
      parameters:
      - name: installation_id
        in: path
        required: true
        schema:
          type: integer
          title: Installation Id
      - name: repo_full_name
        in: query
        required: true
        schema:
          type: string
          description: Full name of the repository
          title: Repo Full Name
        description: Full name of the repository
      - 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: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of branches per page
          default: 100
          title: Limit
        description: Number of branches per page
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search branches by name (case-insensitive substring match)
          title: Search
        description: Search branches by name (case-insensitive substring match)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchesListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
  /api/github/public-repo-branches:
    get:
      tags:
      - GitHub integration
      summary: Get branches for a repository URL
      description: Fetch available branches for a repository URL from its git provider (GitHub or Azure DevOps) with pagination support. When `search` is provided, `page` and `limit` are ignored and all matching branches are returned as a single result set.
      operationId: get_public_repo_branches
      parameters:
      - name: repo_url
        in: query
        required: true
        schema:
          type: string
          description: Full repository URL (e.g., https://github.com/owner/repo or https://dev.azure.com/org/project/_git/repo)
          title: Repo Url
        description: Full repository URL (e.g., https://github.com/owner/repo or https://dev.azure.com/org/project/_git/repo)
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of branches per page
          default: 30
          title: Limit
        description: Number of branches per page
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search branches by name (case-insensitive substring match)
          title: Search
        description: Search branches by name (case-insensitive substring match)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRepoBranchesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Repository not found or not accessible
          content:
            application/json:
              examples:
                not_found:
                  summary: Repository not found
                  value:
                    error: Repository not found or not accessible
                    detail: The repository does not exist or cannot be read with the provider's configured credentials.
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
        '400':
          description: Invalid repository URL format
          content:
            application/json:
              examples:
                invalid_url:
                  summary: Unsupported provider URL
                  value:
                    error: No git provider recognizes this repository URL
                    detail: Provide a repository URL for a supported provider (e.g. https://github.com/owner/repo or https://dev.azure.com/org/project/_git/repo).
                invalid_format:
                  summary: Invalid URL format
                  value:
                    error: Invalid repository URL format
                    detail: The URL must name both the owner/project and the repository.
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
  /api/github/installations/status:
    get:
      tags:
      - GitHub integration
      summary: Get installation status
      description: Check the GitHub App installation status for the current user/organization. Returns connected, pending_approval, not_connected, or expired.
      operationId: get_github_installation_status
      parameters:
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Organization ID to check status for
          title: Organization Id
        description: Organization ID to check status for
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallationStatusResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
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
    GitHubRepository:
      properties:
        name:
          type: string
          title: Name
        full_name:
          type: string
          title: Full Name
        owner:
          $ref: '#/components/schemas/GitHubRepoOwner'
        private:
          type: boolean
          title: Private
        html_url:
          type: string
          title: Html Url
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        pushed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Pushed At
        git_url:
          type: string
          title: Git Url
        ssh_url:
          type: string
          title: Ssh Url
        clone_url:
          type: string
          title: Clone Url
        size:
          type: integer
          title: Size
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        archived:
          type: boolean
          title: Archived
        disabled:
          type: boolean
          title: Disabled
        visibility:
          type: string
          title: Visibility
        default_branch:
          type: string
          title: Default Branch
        permissions:
          additionalProperties:
            type: boolean
          type: object
          title: Permissions
      type: object
      required:
      - name
      - full_name
      - owner
      - private
      - html_url
      - description
      - pushed_at
      - git_url
      - ssh_url
      - clone_url
      - size
      - language
      - archived
      - disabled
      - visibility
      - default_branch
      - permissions
      title: GitHubRepository
      description: GitHub repository information
    GitHubRepoOwner:
      properties:
        login:
          type: string
          title: Login
        type:
          type: string
          title: Type
      type: object
      required:
      - login
      - type
      title: GitHubRepoOwner
      description: GitHub repository owner information
    PublicRepoBranchesResponse:
      properties:
        results:
          items:
            type: string
          type: array
          title: Results
        count:
          type: integer
          title: Count
        repo_full_name:
          type: string
          title: Repo Full Name
        default_branch:
          type: string
          title: Default Branch
        limit:
          type: integer
          title: Limit
        page:
          type: integer
          title: Page
        has_next:
          type: boolean
          title: Has Next
          default: false
      type: object
      required:
      - results
      - count
      - repo_full_name
      - default_branch
      - limit
      - page
      title: PublicRepoBranchesResponse
      description: Response for public repository branches
    PaginatedReposListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/GitHubRepository'
          type: array
          title: Results
        count:
          type: integer
          title: Count
        limit:
          type: integer
          title: Limit
        page:
          type: integer
          title: Page
        has_next:
          type: boolean
          title: Has Next
          default: false
        installation_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Installation Id
      type: object
      required:
      - results
      - count
      - limit
      - page
      title: PaginatedReposListResponse
    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.
    InstallationListItem:
      properties:
        id:
          type: integer
          title: Id
        installation_id:
          type: integer
          title: Installation Id
        provider:
          type: string
          title: Provider
          default: github
        account_login:
          type: string
          title: Account Login
        account_type:
          type: string
          title: Account Type
        alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Alias
        target_type:
          type: string
          title: Target Type
        repository_selection:
          type: string
          title: Repository Selection
        permissions:
          additionalProperties: true
          type: object
          title: Permissions
        is_active:
          type: boolean
          title: Is Active
        installed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Installed At
        installed_by_user_id:
          type: string
          title: Installed By User Id
        is_personal:
          type: boolean
          title: Is Personal
        visibility:
          type: string
          title: Visibility
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          default: ''
        status_code:
          type: integer
          title: Status Code
          default: 400
        github_app_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Github App Key
      type: object
      required:
      - id
      - installation_id
      - account_login
      - account_type
      - alias
      - target_type
      - repository_selection
      - permissions
      - is_active
      - installed_at
      - installed_by_user_id
      - is_personal
      - visibility
      title: InstallationListItem
      description: Enhanced installation list item with visibility info
    RemoveInstallationResponse:
      properties:
        uninstalled_from_github:
          type: boolean
          title: Uninstalled From Github
          description: True when the GitHub App was also uninstalled from the GitHub account, which only happens once no other organization holds the installation. False means the organization was disconnected and the app is still installed for the others.
        message:
          type: string
          title: Message
          description: Human-readable summary of what was disconnected.
      type: object
      required:
      - uninstalled_from_github
      - message
      title: RemoveInstallationResponse
      description: 'Result of disconnecting an installation from the requesting organization.


        A 200 always means the organization was disconnected. Every failure is an error

        response, so there is no success flag to inspect.'
    DetailedInstallationResponse:
      properties:
        installations:
          items:
            $ref: '#/components/schemas/InstallationListItem'
          type: array
          title: Installations
        installation_count:
          type: integer
          title: Installation Count
      type: object
      required:
      - installations
      - installation_count
      title: DetailedInstallationResponse
      description: Response model for detailed installation information
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ErrorResponseSchema:
      properties:
        error:
          type: string
          title: Error
          description: Error message
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
          description: Detailed error information
      type: object
      required:
      - error
      title: ErrorResponseSchema
      description: Schema for error responses
    InstallationRequest:
      properties:
        next_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Url
          description: Optional dashboard URL to redirect after installation
        github_app_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Github App Key
          description: Optional GitHub app key override (e.g. 'new'). Old UI should not send this.
      type: object
      title: InstallationRequest
      description: Request model for starting installation
    InstallationStatusResponse:
      properties:
        status:
          type: string
          title: Status
        installation_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Installation Id
        github_org:
          anyOf:
          - type: string
          - type: 'null'
          title: Github Org
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
      type: object
      required:
      - status
      title: InstallationStatusResponse
      description: Response for checking installation status
    BranchesListResponse:
      properties:
        results:
          items:
            type: string
          type: array
          title: Results
        count:
          type: integer
          title: Count
        repo_full_name:
          type: string
          title: Repo Full Name
        installation_id:
          type: integer
          title: Installation Id
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        has_next:
          type: boolean
          title: Has Next
      type: object
      required:
      - results
      - count
      - repo_full_name
      - installation_id
      - page
      - limit
      - has_next
      title: BranchesListResponse
      description: Response for listing branches in a repository with pagination
    StartInstallationResponse:
      properties:
        installation_url:
          type: string
          title: Installation Url
      type: object
      required:
      - installation_url
      title: StartInstallationResponse
      description: Response for starting installation
  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)