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.'
  version: 1.26.2
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: Remove a GitHub App installation. Soft-deletes locally and uninstalls from GitHub.
      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: {}
        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 public GitHub repository
      description: Fetch available branches from a public GitHub repository using authenticated GitHub App access for better rate limits 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 GitHub repository URL (e.g., https://github.com/owner/repo)
          title: Repo Url
        description: Full GitHub repository URL (e.g., https://github.com/owner/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 is private
          content:
            application/json:
              examples:
                not_found:
                  summary: Repository not found
                  value:
                    error: Repository not found or is private
                    detail: The specified repository does not exist or is not publicly accessible.
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
        '400':
          description: Invalid repository URL format
          content:
            application/json:
              examples:
                invalid_url:
                  summary: Invalid GitHub URL
                  value:
                    error: Invalid GitHub repository URL. Must start with https://github.com/
                    detail: Only GitHub repositories are supported. Please provide a valid GitHub URL.
                invalid_format:
                  summary: Invalid URL format
                  value:
                    error: 'Invalid GitHub repository URL format. Expected: https://github.com/owner/repo'
                    detail: The URL must contain both owner and repository name.
              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:
    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
    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
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    GitHubRepoOwner:
      properties:
        login:
          type: string
          title: Login
        type:
          type: string
          title: Type
      type: object
      required:
      - login
      - type
      title: GitHubRepoOwner
      description: GitHub repository owner information
    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
    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
    InstallationListItem:
      properties:
        id:
          type: integer
          title: Id
        installation_id:
          type: integer
          title: Installation Id
        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
    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.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    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
    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
    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
  - github_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