CoreStory Marketplace API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Marketplace 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: Marketplace
paths:
  /api/marketplace/connectors/{connector_id}/oauth/start:
    post:
      tags:
      - Marketplace
      summary: Start the OAuth handshake for a connector
      operationId: start_marketplace_oauth
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          title: Connector Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthStartResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/marketplace/connections/{connector_id}/configuration:
    put:
      tags:
      - Marketplace
      summary: Update non-secret configuration values and re-evaluate connection status
      operationId: update_marketplace_configuration
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          title: Connector Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_update_marketplace_configuration'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDetail'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/marketplace/connections/{connector_id}/verify:
    post:
      tags:
      - Marketplace
      summary: Re-check a connection's stored credentials against the provider
      operationId: verify_marketplace_connection
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          title: Connector Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDetail'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/marketplace/connections/{connector_id}/disconnect:
    post:
      tags:
      - Marketplace
      summary: 'Disconnect a connection: remove credentials + configuration (idempotent)'
      operationId: disconnect_marketplace_connection
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          title: Connector Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDetail'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/marketplace/catalog:
    get:
      tags:
      - Marketplace
      summary: List marketplace connectors with per-org status
      description: Return all active connectors annotated with the caller's connection status.
      operationId: list_marketplace_catalog
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/marketplace/catalog/{connector_id}:
    get:
      tags:
      - Marketplace
      summary: Get connector detail with per-org connection record
      description: Return descriptive fields plus the caller org's connection record.
      operationId: get_marketplace_catalog_detail
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          title: Connector Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDetail'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ConnectionType:
      type: string
      enum:
      - oauth_2_0
      title: ConnectionType
      description: How a connector authenticates.
    ConnectionStatus:
      type: string
      enum:
      - not_connected
      - connected_config_required
      - connected_ready
      - error
      - pending
      title: ConnectionStatus
      description: Lifecycle states for an organization's connection to a catalog connector.
    CatalogListItem:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        icon_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon Url
        publisher:
          type: string
          title: Publisher
        trust_badge:
          $ref: '#/components/schemas/TrustBadge'
        connection_type:
          $ref: '#/components/schemas/ConnectionType'
        auth_type:
          type: string
          title: Auth Type
        capability:
          $ref: '#/components/schemas/CapabilitySummary'
        configuration_schema:
          items:
            $ref: '#/components/schemas/ConfigurationField'
          type: array
          title: Configuration Schema
        is_active:
          type: boolean
          title: Is Active
        display_order:
          type: integer
          title: Display Order
        connection_status:
          $ref: '#/components/schemas/ConnectionStatus'
      type: object
      required:
      - id
      - name
      - description
      - icon_url
      - publisher
      - trust_badge
      - connection_type
      - auth_type
      - capability
      - configuration_schema
      - is_active
      - display_order
      - connection_status
      title: CatalogListItem
      description: Catalog entry annotated with the caller's connection status.
    Body_update_marketplace_configuration:
      properties:
        values:
          additionalProperties: true
          type: object
          title: Values
          description: Map keyed by configuration_schema.key.
      type: object
      required:
      - values
      title: Body_update_marketplace_configuration
    CatalogListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CatalogListItem'
          type: array
          title: Items
      type: object
      required:
      - items
      title: CatalogListResponse
    CapabilitySummary:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        operations:
          items:
            type: string
          type: array
          title: Operations
      type: object
      required:
      - id
      - label
      - operations
      title: CapabilitySummary
    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
    CatalogDetail:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        icon_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon Url
        publisher:
          type: string
          title: Publisher
        trust_badge:
          $ref: '#/components/schemas/TrustBadge'
        connection_type:
          $ref: '#/components/schemas/ConnectionType'
        auth_type:
          type: string
          title: Auth Type
        capability:
          $ref: '#/components/schemas/CapabilitySummary'
        configuration_schema:
          items:
            $ref: '#/components/schemas/ConfigurationField'
          type: array
          title: Configuration Schema
        is_active:
          type: boolean
          title: Is Active
        display_order:
          type: integer
          title: Display Order
        connection_status:
          $ref: '#/components/schemas/ConnectionStatus'
        account_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Email
        workspace_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Name
        configuration_values:
          additionalProperties: true
          type: object
          title: Configuration Values
        last_verified_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Verified At
        last_error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error Message
          description: Populated only when connection_status == error.
      type: object
      required:
      - id
      - name
      - description
      - icon_url
      - publisher
      - trust_badge
      - connection_type
      - auth_type
      - capability
      - configuration_schema
      - is_active
      - display_order
      - connection_status
      title: CatalogDetail
      description: Catalog detail adds the caller's current connection record (non-secret).
    OAuthStartResponse:
      properties:
        authorization_url:
          type: string
          title: Authorization Url
          description: Provider authorization URL the FE should redirect to.
        state:
          type: string
          title: State
          description: Single-use state token bound to the caller's org + user.
      type: object
      required:
      - authorization_url
      - state
      title: OAuthStartResponse
      description: Response from ``POST /marketplace/connectors/{id}/oauth/start``.
    ConfigurationField:
      properties:
        key:
          type: string
          title: Key
        label:
          type: string
          title: Label
        type:
          type: string
          title: Type
          description: Input widget hint, e.g. text, select, url, password, email.
        required:
          type: boolean
          title: Required
        help_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Help Text
        placeholder:
          anyOf:
          - type: string
          - type: 'null'
          title: Placeholder
          description: Inline placeholder the FE shows in the empty input.
        options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Options
          description: Allowed values when type=select.
        default:
          anyOf:
          - {}
          - type: 'null'
          title: Default
          description: Pre-selected value the FE applies when no value has been saved.
        sensitive:
          type: boolean
          title: Sensitive
          description: Secret-carrying field (token, webhook URL). Never written via the configuration update endpoint; never returned in configuration_values.
          default: false
      type: object
      required:
      - key
      - label
      - type
      - required
      title: ConfigurationField
      description: One field descriptor in a connector's configuration schema.
    TrustBadge:
      type: string
      enum:
      - verified
      - corestory
      - community
      title: TrustBadge
      description: Trust signal shown on the catalog card.
  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