openapi: 3.1.0
info:
  title: Cobalt Applications Config API
  description: The Cobalt API enables developers to programmatically manage integrations, linked accounts, configurations, events, webhooks, executions, public workflows, and datastores within the Cobalt embedded integration platform. Cobalt helps product and engineering teams build native integrations, deploy them within days, and monetize them with the help of AI agents.
  version: 2.0.0
  contact:
    name: Cobalt Support
    url: https://www.gocobalt.io/
  termsOfService: https://docs.gocobalt.io/governance/terms-of-use
  license:
    name: Proprietary
    url: https://docs.gocobalt.io/governance/terms-of-use
servers:
- url: https://api.gocobalt.io/api/v2
  description: Cobalt Production API
security:
- apiKey: []
tags:
- name: Config
  description: Manage integration configurations for linked accounts.
paths:
  /public/config:
    post:
      operationId: upsertConfig
      summary: Cobalt Upsert Config
      description: Creates a new configuration or returns the existing one for the specified linked account and application. Configs store customizations for each integration of your end-customers.
      tags:
      - Config
      parameters:
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - slug
              properties:
                slug:
                  type: string
                  description: The application slug.
                config_id:
                  type: string
                  description: Optional config ID for specific config retrieval.
      responses:
        '200':
          description: Config upserted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '401':
          description: Unauthorized - Invalid API key.
  /public/config/{config_id}:
    get:
      operationId: getConfigById
      summary: Cobalt Get Config by ID
      description: Returns a configuration by its unique identifier.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Config retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '404':
          description: Config not found.
        '401':
          description: Unauthorized - Invalid API key.
    put:
      operationId: updateConfig
      summary: Cobalt Update Config
      description: Updates an existing configuration with fields and workflows.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  description: Configuration fields to update.
                workflows:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      enabled:
                        type: boolean
                  description: Workflow enablement settings.
      responses:
        '200':
          description: Config updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '404':
          description: Config not found.
        '401':
          description: Unauthorized - Invalid API key.
    delete:
      operationId: deleteConfig
      summary: Cobalt Delete Config
      description: Deletes a configuration by its unique identifier.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Config deleted successfully.
        '404':
          description: Config not found.
        '401':
          description: Unauthorized - Invalid API key.
  /public/config/all:
    get:
      operationId: listInstalledConfigs
      summary: Cobalt Get All Installed Configs
      description: Returns all installed configurations for a linked account.
      tags:
      - Config
      parameters:
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: List of configs retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Config'
        '401':
          description: Unauthorized - Invalid API key.
  /public/config/{config_id}/fields:
    get:
      operationId: getConfigFields
      summary: Cobalt Get All Config Fields
      description: Returns all fields for a specific configuration.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Config fields retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    value:
                      type: string
        '404':
          description: Config not found.
        '401':
          description: Unauthorized - Invalid API key.
  /public/config/{config_id}/field/{field_id}:
    get:
      operationId: getFieldValueById
      summary: Cobalt Get Field Value by ID in Config
      description: Returns a specific field value from a configuration.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: field_id
        in: path
        required: true
        schema:
          type: string
        description: The field ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Field value retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  value:
                    type: string
        '404':
          description: Field or config not found.
        '401':
          description: Unauthorized - Invalid API key.
    put:
      operationId: updateFieldValueById
      summary: Cobalt Update Field Value by ID in Config
      description: Updates a specific field value in a configuration.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: field_id
        in: path
        required: true
        schema:
          type: string
        description: The field ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: The new field value.
      responses:
        '200':
          description: Field value updated successfully.
        '404':
          description: Field or config not found.
        '401':
          description: Unauthorized - Invalid API key.
    delete:
      operationId: deleteFieldValueById
      summary: Cobalt Delete Field Value by ID in Config
      description: Deletes a specific field value from a configuration.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: field_id
        in: path
        required: true
        schema:
          type: string
        description: The field ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Field value deleted successfully.
        '404':
          description: Field or config not found.
        '401':
          description: Unauthorized - Invalid API key.
  /public/config/{config_id}/rule-engine/options:
    get:
      operationId: getRuleEngineOptions
      summary: Cobalt Get Options for Rule Engine
      description: Returns the available options for the rule engine of a configuration.
      tags:
      - Config
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
        description: The configuration ID.
      - name: linked_account_id
        in: header
        required: true
        schema:
          type: string
        description: The linked account ID.
      responses:
        '200':
          description: Rule engine options retrieved successfully.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Config not found.
        '401':
          description: Unauthorized - Invalid API key.
components:
  schemas:
    Config:
      type: object
      properties:
        _id:
          type: string
          description: Configuration ID.
        slug:
          type: string
          description: Application slug.
        linked_account_id:
          type: string
          description: The linked account ID.
        fields:
          type: object
          description: Configuration fields.
        workflows:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              enabled:
                type: boolean
          description: Workflow enablement settings.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Found in Cobalt dashboard under Settings > Developer > Setup tab.
    sessionToken:
      type: apiKey
      in: header
      name: Authorization
      description: Session token generated via the Session Token endpoint.