Kombo API

naftiko: 1.0.0-alpha2
info:
  label: Kombo API
  description: 'Kombo API. 13 operations. Lead operation: Check API key. Self-contained Naftiko capability covering one Kombo
    business surface.'
  tags:
  - Kombo
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    KOMBO_API_KEY: KOMBO_API_KEY
capability:
  consumes:
  - type: http
    namespace: kombo-general
    baseUri: https://api.kombo.dev/v1
    description: Kombo API business capability. Self-contained, no shared references.
    resources:
    - name: check-api-key
      path: /check-api-key
      operations:
      - name: getcheckapikey
        method: GET
        description: Check API key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: force-sync
      path: /force-sync
      operations:
      - name: postforcesync
        method: POST
        description: Trigger sync
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: X-Integration-Id
          in: header
          type: string
          description: ID of the integration you want to interact with.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: integrations-integration_id
      path: /integrations/{integration_id}
      operations:
      - name: deleteintegrationsintegrationid
        method: DELETE
        description: Delete integration
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: DELETE /integrations/:integration_id Parameter
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: getintegrationsintegrationid
        method: GET
        description: Get integration details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: GET /integrations/:integration_id Parameter
          required: true
    - name: integrations-integration_id-custom-fields
      path: /integrations/{integration_id}/custom-fields
      operations:
      - name: getintegrationsintegrationidcustomfields
        method: GET
        description: Get custom fields with current mappings
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: GET /integrations/:integration_id/custom-fields Parameter
          required: true
        - name: cursor
          in: query
          type: string
          description: An optional cursor string used for pagination. This can be retrieved from the `next` property of the
            previous page response.
        - name: page_size
          in: query
          type: string
          description: The number of results to return per page. Maximum is 250.
    - name: integrations-integration_id-custom-fields-custom_field_id
      path: /integrations/{integration_id}/custom-fields/{custom_field_id}
      operations:
      - name: putintegrationsintegrationidcustomfieldscustomfieldid
        method: PUT
        description: Put custom field mappings
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: The unique ID of the integration where the custom field mapping should be updated
          required: true
        - name: custom_field_id
          in: path
          type: string
          description: The unique ID of the custom field that should be updated
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: integrations-integration_id-enabled
      path: /integrations/{integration_id}/enabled
      operations:
      - name: putintegrationsintegrationidenabled
        method: PUT
        description: Set integration enabled
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: PUT /integrations/:integration_id/enabled Parameter
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: integrations-integration_id-integration-fields
      path: /integrations/{integration_id}/integration-fields
      operations:
      - name: getintegrationsintegrationidintegrationfields
        method: GET
        description: Get integration fields
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: GET /integrations/:integration_id/integration-fields Parameter
          required: true
        - name: cursor
          in: query
          type: string
          description: An optional cursor string used for pagination. This can be retrieved from the `next` property of the
            previous page response.
        - name: page_size
          in: query
          type: string
          description: The number of results to return per page. Maximum is 2000.
    - name: integrations-integration_id-integration-fields-integration_field_id
      path: /integrations/{integration_id}/integration-fields/{integration_field_id}
      operations:
      - name: patchintegrationsintegrationidintegrationfieldsintegrationfieldid
        method: PATCH
        description: Updates an integration fields passthrough setting
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: PATCH /integrations/:integration_id/integration-fields/:integration_field_id Parameter
          required: true
        - name: integration_field_id
          in: path
          type: string
          description: PATCH /integrations/:integration_id/integration-fields/:integration_field_id Parameter
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: integrations-integration_id-relink
      path: /integrations/{integration_id}/relink
      operations:
      - name: postintegrationsintegrationidrelink
        method: POST
        description: Create reconnection link
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: POST /integrations/:integration_id/relink Parameter
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: integrations-integration_id-setup-link
      path: /integrations/{integration_id}/setup-link
      operations:
      - name: postintegrationsintegrationidsetuplink
        method: POST
        description: Create Setup Flow link
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: integration_id
          in: path
          type: string
          description: POST /integrations/:integration_id/setup-link Parameter
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: passthrough-tool-api
      path: /passthrough/{tool}/{api}
      operations:
      - name: postpassthroughtoolapi
        method: POST
        description: Send passthrough request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: X-Integration-Id
          in: header
          type: string
          description: ID of the integration you want to interact with.
          required: true
        - name: tool
          in: path
          type: string
          description: The ID of the tool whose passthrough API you want to call (e.g., `personio`).
          required: true
        - name: api
          in: path
          type: string
          description: The ID of the passthrough API you want to call (some tools provide multiple). Check the endpoint description
            for a list of all available APIs.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: tools-category
      path: /tools/{category}
      operations:
      - name: gettoolscategory
        method: GET
        description: Get tools
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category
          in: path
          type: string
          description: GET /tools/:category Parameter
          required: true
    authentication:
      type: bearer
      token: '{{env.KOMBO_API_KEY}}'
  exposes:
  - type: rest
    namespace: kombo-general-rest
    port: 8080
    description: REST adapter for Kombo API. One Spectral-compliant resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/check-api-key
      name: check-api-key
      description: REST surface for check-api-key.
      operations:
      - method: GET
        name: getcheckapikey
        description: Check API key
        call: kombo-general.getcheckapikey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/force-sync
      name: force-sync
      description: REST surface for force-sync.
      operations:
      - method: POST
        name: postforcesync
        description: Trigger sync
        call: kombo-general.postforcesync
        with:
          X-Integration-Id: rest.X-Integration-Id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}
      name: integrations-integration-id
      description: REST surface for integrations-integration_id.
      operations:
      - method: DELETE
        name: deleteintegrationsintegrationid
        description: Delete integration
        call: kombo-general.deleteintegrationsintegrationid
        with:
          integration_id: rest.integration_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getintegrationsintegrationid
        description: Get integration details
        call: kombo-general.getintegrationsintegrationid
        with:
          integration_id: rest.integration_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/custom-fields
      name: integrations-integration-id-custom-fields
      description: REST surface for integrations-integration_id-custom-fields.
      operations:
      - method: GET
        name: getintegrationsintegrationidcustomfields
        description: Get custom fields with current mappings
        call: kombo-general.getintegrationsintegrationidcustomfields
        with:
          integration_id: rest.integration_id
          cursor: rest.cursor
          page_size: rest.page_size
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/custom-fields/{custom-field-id}
      name: integrations-integration-id-custom-fields-custom-field-id
      description: REST surface for integrations-integration_id-custom-fields-custom_field_id.
      operations:
      - method: PUT
        name: putintegrationsintegrationidcustomfieldscustomfieldid
        description: Put custom field mappings
        call: kombo-general.putintegrationsintegrationidcustomfieldscustomfieldid
        with:
          integration_id: rest.integration_id
          custom_field_id: rest.custom_field_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/enabled
      name: integrations-integration-id-enabled
      description: REST surface for integrations-integration_id-enabled.
      operations:
      - method: PUT
        name: putintegrationsintegrationidenabled
        description: Set integration enabled
        call: kombo-general.putintegrationsintegrationidenabled
        with:
          integration_id: rest.integration_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/integration-fields
      name: integrations-integration-id-integration-fields
      description: REST surface for integrations-integration_id-integration-fields.
      operations:
      - method: GET
        name: getintegrationsintegrationidintegrationfields
        description: Get integration fields
        call: kombo-general.getintegrationsintegrationidintegrationfields
        with:
          integration_id: rest.integration_id
          cursor: rest.cursor
          page_size: rest.page_size
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/integration-fields/{integration-field-id}
      name: integrations-integration-id-integration-fields-integration-field-id
      description: REST surface for integrations-integration_id-integration-fields-integration_field_id.
      operations:
      - method: PATCH
        name: patchintegrationsintegrationidintegrationfieldsintegrationfieldid
        description: Updates an integration fields passthrough setting
        call: kombo-general.patchintegrationsintegrationidintegrationfieldsintegrationfieldid
        with:
          integration_id: rest.integration_id
          integration_field_id: rest.integration_field_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/relink
      name: integrations-integration-id-relink
      description: REST surface for integrations-integration_id-relink.
      operations:
      - method: POST
        name: postintegrationsintegrationidrelink
        description: Create reconnection link
        call: kombo-general.postintegrationsintegrationidrelink
        with:
          integration_id: rest.integration_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/integrations/{integration-id}/setup-link
      name: integrations-integration-id-setup-link
      description: REST surface for integrations-integration_id-setup-link.
      operations:
      - method: POST
        name: postintegrationsintegrationidsetuplink
        description: Create Setup Flow link
        call: kombo-general.postintegrationsintegrationidsetuplink
        with:
          integration_id: rest.integration_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/passthrough/{tool}/{api}
      name: passthrough-tool-api
      description: REST surface for passthrough-tool-api.
      operations:
      - method: POST
        name: postpassthroughtoolapi
        description: Send passthrough request
        call: kombo-general.postpassthroughtoolapi
        with:
          X-Integration-Id: rest.X-Integration-Id
          tool: rest.tool
          api: rest.api
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tools/{category}
      name: tools-category
      description: REST surface for tools-category.
      operations:
      - method: GET
        name: gettoolscategory
        description: Get tools
        call: kombo-general.gettoolscategory
        with:
          category: rest.category
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: kombo-general-mcp
    port: 9090
    transport: http
    description: MCP adapter for Kombo API. One tool per consumed operation, routed inline through this capability's consumes
      block.
    tools:
    - name: check-api-key
      description: Check API key
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kombo-general.getcheckapikey
      outputParameters:
      - type: object
        mapping: $.
    - name: trigger-sync
      description: Trigger sync
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: kombo-general.postforcesync
      with:
        X-Integration-Id: tools.X-Integration-Id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-integration
      description: Delete integration
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: kombo-general.deleteintegrationsintegrationid
      with:
        integration_id: tools.integration_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-integration-details
      description: Get integration details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kombo-general.getintegrationsintegrationid
      with:
        integration_id: tools.integration_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-custom-fields-current-mappings
      description: Get custom fields with current mappings
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kombo-general.getintegrationsintegrationidcustomfields
      with:
        integration_id: tools.integration_id
        cursor: tools.cursor
        page_size: tools.page_size
      outputParameters:
      - type: object
        mapping: $.
    - name: put-custom-field-mappings
      description: Put custom field mappings
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: kombo-general.putintegrationsintegrationidcustomfieldscustomfieldid
      with:
        integration_id: tools.integration_id
        custom_field_id: tools.custom_field_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: set-integration-enabled
      description: Set integration enabled
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: kombo-general.putintegrationsintegrationidenabled
      with:
        integration_id: tools.integration_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-integration-fields
      description: Get integration fields
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kombo-general.getintegrationsintegrationidintegrationfields
      with:
        integration_id: tools.integration_id
        cursor: tools.cursor
        page_size: tools.page_size
      outputParameters:
      - type: object
        mapping: $.
    - name: updates-integration-fields-passthrough-setting
      description: Updates an integration fields passthrough setting
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: kombo-general.patchintegrationsintegrationidintegrationfieldsintegrationfieldid
      with:
        integration_id: tools.integration_id
        integration_field_id: tools.integration_field_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: create-reconnection-link
      description: Create reconnection link
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: kombo-general.postintegrationsintegrationidrelink
      with:
        integration_id: tools.integration_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: create-setup-flow-link
      description: Create Setup Flow link
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: kombo-general.postintegrationsintegrationidsetuplink
      with:
        integration_id: tools.integration_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: send-passthrough-request
      description: Send passthrough request
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: kombo-general.postpassthroughtoolapi
      with:
        X-Integration-Id: tools.X-Integration-Id
        tool: tools.tool
        api: tools.api
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tools
      description: Get tools
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: kombo-general.gettoolscategory
      with:
        category: tools.category
      outputParameters:
      - type: object
        mapping: $.