Starbridge Columns API

openapi: 3.1.1
info:
  title: Starbridge External Public Bridges Columns API
  version: '1.0'
servers:
- url: https://dashboard.starbridge.ai
tags:
- name: Columns
paths:
  /api/external/bridge/{bridgeId}/column/metadata:
    get:
      operationId: getBridgeColumnMetadata
      tags:
      - Columns
      summary: List existing columns with their per-type settings
      description: 'Use to inspect which columns already exist on this bridge and how they are configured.

        Returns each column''s per-type settings not carried by `getBridge` (link settings,

        web-agent model, vendor presence, email generation, webhook URL, cross-bridge cell mirror) plus

        `additionalFields` synthetic refs (e.g. `{columnId$basis:firstName}`) usable in

        prompts or as `referenceFieldPath` on `createReferenceColumn`. Cross-reference entries

        to the bridge''s columns from `getBridge` by `columnId` for the base column shape.'
      parameters:
      - name: bridgeId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Per-column metadata for existing columns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BridgeExistingColumnMetadata'
        '400':
          description: Invalid request body or format
        '401':
          description: Missing or invalid authentication
        '403':
          description: Unauthorized to access resource or perform action
        '415':
          description: Unsupported media type or request body format
        '404':
          description: Resource not found
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      security:
      - apiKey: []
      x-mcp-annotations:
        readOnlyHint: true
        destructiveHint: false
        idempotentHint: true
        openWorldHint: false
components:
  schemas:
    BridgeObjFieldDefinition:
      type: object
      title: BridgeObjFieldDefinition
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Name of the field
        type:
          type: string
          description: Data type of the field
          enum:
          - text
          - date
          - url
          - number
          - enumeration
          - list
          - obj
          - json
          - phone
          - email
          - boolean
          - currencyUnit
        description:
          type:
          - string
          - 'null'
          description: Optional description of the field
    WebContactSettings:
      type: object
      title: WebContactSettings
      required:
      - subPrompt
      properties:
        subPrompt:
          type: string
        examples:
          type:
          - array
          - 'null'
          items:
            type: string
        additionalContext:
          type:
          - string
          - 'null'
    TriggerFilters:
      type: object
      title: TriggerFilters
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/TriggerFiltersTermGroup'
    BridgeFieldFormat:
      type: object
      title: BridgeFieldFormat
      description: Field format specification for the column
      required:
      - baseFormat
      properties:
        baseFormat:
          type: string
          description: Base data type of the field (String, Integer, Boolean, etc.)
          enum:
          - text
          - date
          - url
          - number
          - enumeration
          - list
          - obj
          - json
          - phone
          - email
          - boolean
          - currencyUnit
        description:
          type:
          - string
          - 'null'
          description: Optional description of the field
        enumerationValues:
          type:
          - array
          - 'null'
          description: Optional list of enumeration values if field is a select type
          items:
            $ref: '#/components/schemas/FieldFormatEnumerationValue'
        currency:
          type:
          - string
          - 'null'
          description: Optional currency type if field represents a monetary value
          enum:
          - USD
          - CAD
        listElementBaseFormat:
          type:
          - string
          - 'null'
          description: Base format type for list elements if field is a list type
          enum:
          - text
          - date
          - url
          - number
          - enumeration
          - list
          - obj
          - json
          - phone
          - email
          - boolean
          - currencyUnit
        outputFields:
          type:
          - array
          - 'null'
          description: Optional field definitions for object type fields
          items:
            $ref: '#/components/schemas/BridgeObjFieldDefinition'
    AccountScoringFitColumnConfig:
      type: object
      title: AccountScoringFitColumnConfig
      required:
      - phaseId
      properties:
        phaseId:
          type: string
          format: uuid
        includedInScoring:
          type: boolean
        weight:
          type: string
          enum:
          - High
          - Medium
          - Low
        strongFitGuidance:
          type:
          - string
          - 'null'
    AccountScoringConfig:
      type: object
      title: AccountScoringConfig
      properties:
        fitColumns:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AccountScoringFitColumnConfig'
        signalConfigs:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/AccountScoringSignalTypeConfig'
        fitInteractionPrompt:
          type:
          - string
          - 'null'
        signalInteractionPrompt:
          type:
          - string
          - 'null'
    BridgeLinkToCellSettings:
      type: object
      title: BridgeLinkToCellSettings
      description: Cross-bridge cell-mirror settings — set on LinkToCell columns.
      required:
      - targetBridgeId
      - targetColumnId
      - sourceRowIdentity
      properties:
        targetBridgeId:
          type: string
          description: Bridge whose cell this column mirrors
          format: uuid
        targetColumnId:
          type: string
          description: Column in the target bridge whose value is mirrored
          format: uuid
        sourceRowIdentity:
          type: string
          description: How the matching target row is identified from this row (e.g. InherentOpportunityId, ContactColumn)
    FieldFormatEnumerationValue:
      type: object
      title: FieldFormatEnumerationValue
      required:
      - value
      properties:
        value:
          type: string
        label:
          type: string
    BridgeExistingColumnMetadata:
      type: object
      title: BridgeExistingColumnMetadata
      required:
      - columnId
      - bridgeId
      - column
      - additionalFields
      properties:
        columnId:
          type: string
          description: UUID of the existing column. Duplicated from `column.columnId` for backwards compatibility.
          format: uuid
        bridgeId:
          type: string
          description: UUID of the bridge this column belongs to. Duplicated from `column.bridgeId` for backwards compatibility.
          format: uuid
        column:
          $ref: '#/components/schemas/BridgeColumnResponse'
        additionalFields:
          type: array
          description: Extra reference paths exposed by this column. For basis columns (e.g. a Get Contact column that attaches contact records), these surface synthetic refs like `{columnId$basis:firstName}` you can plug into prompts or `referenceFieldPath` on createReferenceColumn.
          items:
            $ref: '#/components/schemas/BridgeRowAttributeOption'
        webAgentModel:
          type:
          - string
          - 'null'
          description: Web agent model — set on web-agent columns.
          enum:
          - Lite
          - Base
          - Core
          - Core2X
          - Pro
          - Ultra
          - UltraTwoX
          - UltraFourX
          - UltraEightX
        linkSettings:
          $ref: '#/components/schemas/BridgeLinkSettings'
        vendorPresenceSettings:
          oneOf:
          - $ref: '#/components/schemas/BridgeCompetitorPresenceSettings'
          - type: 'null'
        emailGenerationSettings:
          oneOf:
          - $ref: '#/components/schemas/BridgeEmailGenerationSettings'
          - type: 'null'
        webhookUrl:
          type:
          - string
          - 'null'
          description: Webhook URL — set on webhook columns.
        linkToCellSettings:
          oneOf:
          - $ref: '#/components/schemas/BridgeLinkToCellSettings'
          - type: 'null'
        multiLinkSettings:
          oneOf:
          - $ref: '#/components/schemas/BridgeMultiLinkSettings'
          - type: 'null'
        webContactSettings:
          oneOf:
          - $ref: '#/components/schemas/WebContactSettings'
          - type: 'null'
        accountScoringMetadata:
          oneOf:
          - $ref: '#/components/schemas/AccountScoringMetadata'
          - type: 'null'
        runConditions:
          $ref: '#/components/schemas/TriggerFilters'
    TriggerFiltersTermGroup:
      type: object
      title: TriggerFiltersTermGroup
      properties:
        terms:
          type: array
          items:
            $ref: '#/components/schemas/TriggerFiltersTerm'
    BridgeRowAttributeOption:
      type: object
      title: BridgeRowAttributeOption
      required:
      - key
      - name
      - fieldFormat
      properties:
        key:
          type: string
          description: Attribute key, e.g. `op:until_date`, `buyer:name`
        name:
          type: string
          description: Human-readable label
        fieldFormat:
          $ref: '#/components/schemas/BridgeFieldFormat'
    BridgeLinkSettings:
      type: object
      title: BridgeLinkSettings
      required:
      - sourceBridgeId
      - includedStatuses
      properties:
        sourceBridgeId:
          type: string
          description: UUID of the referenced (source) bridge whose rows this link column pulls in - i.e. the other bridge, not the bridge this column belongs to
          format: uuid
        includedStatuses:
          type: array
          description: Row statuses included from the source bridge
          items:
            type: string
        maxAgeRelativePeriod:
          type:
          - string
          - 'null'
          description: Max age window for source rows relative to now. Null when no age cap is applied.
          enum:
          - Future
          - NextTwoYears
          - NextYear
          - NextNineMonths
          - NextSixMonths
          - NextThreeMonths
          - NextTwoMonths
          - NextOneMonth
          - NextSixtyDays
          - NextThirtyDays
          - NextSevenDays
          - NextOneDay
          - Present
          - LastOneDay
          - LastSevenDays
          - LastThirtyDays
          - LastSixtyDays
          - LastOneMonths
          - LastTwoMonths
          - LastThreeMonths
          - LastSixMonths
          - LastNineMonths
          - LastYear
          - LastTwoYears
          - Past
        filters:
          $ref: '#/components/schemas/TriggerFilters'
    BridgeEmailGenerationSettings:
      type: object
      title: BridgeEmailGenerationSettings
      description: Email generation settings — set on email template columns.
      required:
      - emailSubjectTemplate
      - emailBodyTemplate
      properties:
        emailSubjectTemplate:
          type: string
        emailBodyTemplate:
          type: string
        showParentColumn:
          type: boolean
        snippetDefinitions:
          type:
          - object
          - 'null'
          description: Map of snippet name to generation prompt. Prompts can contain {columnId} references.
          additionalProperties:
            type: string
    SignalBridgeConfig:
      type: object
      title: SignalBridgeConfig
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
        enabled:
          type: boolean
    AccountScoringMetadata:
      type: object
      title: AccountScoringMetadata
      properties:
        scoringConfig:
          $ref: '#/components/schemas/AccountScoringConfig'
        signalBridgesByType:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SignalBridgeConfig'
    AccountScoringSignalTypeConfig:
      type: object
      title: AccountScoringSignalTypeConfig
      properties:
        weight:
          type: string
          enum:
          - High
          - Medium
          - Low
        guidance:
          type:
          - string
          - 'null'
    CompetitorPresenceSettingsServiceProvider:
      type: object
      title: CompetitorPresenceSettingsServiceProvider
      required:
      - name
      properties:
        name:
          type: string
        serviceProviderAliases:
          type:
          - array
          - 'null'
          items:
            type: string
        productNamesOrAliases:
          type:
          - array
          - 'null'
          items:
            type: string
    BridgeColumnResponse:
      type: object
      title: BridgeColumnResponse
      required:
      - columnId
      - bridgeId
      - name
      - prompt
      - type
      - fieldFormat
      - index
      properties:
        columnId:
          type: string
          description: Unique identifier for the column
          format: uuid
        bridgeId:
          type: string
          description: UUID of the bridge this column belongs to
          format: uuid
        name:
          type: string
          description: Display name of the column
        prompt:
          type: string
          description: Prompt or instruction for generating column values
        type:
          type: string
          description: Type of column (AiAnalysis, DataAttribute, AiAnalysisTemplate, etc.)
          enum:
          - AiAnalysis
          - DataAttribute
          - AiAnalysisTemplate
          - WebAgentTemplate
          - Input
          - Link
          - CrmLookup
          - CrmSync
          - LinkToCell
          - CompetitorsPresence
          - EmailTemplate
          - PhoneCallTemplate
          - Webhook
          - MultiLink
          - AccountScoring
        fieldFormat:
          $ref: '#/components/schemas/BridgeFieldFormat'
        index:
          type: integer
          description: Zero-based index position of the column
        key:
          type:
          - string
          - 'null'
          description: Optional key for referencing the column
    BridgeMultiLinkSettings:
      type: object
      title: BridgeMultiLinkSettings
      description: MultiLink settings — set on multi-link columns.
      required:
      - sourceBridgeIds
      - includedStatuses
      properties:
        sourceBridgeIds:
          type: array
          description: UUIDs of the referenced (source) bridges whose rows these link columns pull in - i.e. the other bridges, not the bridge these columns belong to
          items:
            type: string
            format: uuid
        includedStatuses:
          type: array
          description: Row statuses included from the source bridges
          items:
            type: string
        maxAgeRelativePeriod:
          type:
          - string
          - 'null'
          description: Max age window for source rows relative to now. Null when no age cap is applied.
          enum:
          - Future
          - NextTwoYears
          - NextYear
          - NextNineMonths
          - NextSixMonths
          - NextThreeMonths
          - NextTwoMonths
          - NextOneMonth
          - NextSixtyDays
          - NextThirtyDays
          - NextSevenDays
          - NextOneDay
          - Present
          - LastOneDay
          - LastSevenDays
          - LastThirtyDays
          - LastSixtyDays
          - LastOneMonths
          - LastTwoMonths
          - LastThreeMonths
          - LastSixMonths
          - LastNineMonths
          - LastYear
          - LastTwoYears
          - Past
    TriggerFiltersTerm:
      type: object
      title: TriggerFiltersTerm
      required:
      - field
      - operation
      properties:
        field:
          type: string
        operation:
          type: string
          enum:
          - Equals
          - DoesNotEqual
          - Contains
          - DoesNotContain
          - GreaterThan
          - LessThan
          - IsEmpty
          - IsNotEmpty
          - Any
          - None
          - ContainsAny
          - ContainsAll
          - ContainedBy
          - NotContainedBy
          - HasCellStatus
          - HasLookupStatus
          - HasLastSyncStatus
          - HasSyncStatusHistory
        value:
          description: Any JSON value - can be a string, number, boolean, object, array, or null
    BridgeCompetitorPresenceSettings:
      type: object
      title: BridgeCompetitorPresenceSettings
      description: Vendor presence settings — set on vendor presence columns.
      required:
      - serviceProviders
      - runWebPresence
      properties:
        serviceProviders:
          type: array
          items:
            $ref: '#/components/schemas/CompetitorPresenceSettingsServiceProvider'
        runWebPresence:
          type: boolean
        contextPrompt:
          type:
          - string
          - 'null'
        runContractEstimation:
          type: boolean
  securitySchemes:
    apiKey:
      scheme: bearer
      description: HTTP Bearer Authentication
      type: http