openapi: 3.0.0
info:
  title: OpenAPI Specification Agents - Conversation OpenAPI Tool Calling API
  description: AI API to chat with Celonis Agents and run their tools.
  x-audience: EX
  version: v1.2.0
servers:
- url: https://30f873b4-88d4-49ba-b327-6f651d7b99e6.remockly.com
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: OpenAPI Tool Calling
  description: OpenAPI endpoints for calling tools configured in the Agent Tools (MCP) Asset.
paths:
  /studio-copilot/api/v1/mcp-servers/mcp/{asset_id}/tool-api/{tool_id}:
    post:
      tags:
      - OpenAPI Tool Calling
      summary: Call Agent Tools (MCP) Asset Tool
      operationId: postMcpServerToolResponse
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
          title: Asset Id
          example: dba9e6e8-7fbf-42f9-baf4-78747fb3e125
      - name: tool_id
        in: path
        required: true
        description: Tool ID as configured in the asset (for example, `search-data` or `load-data`).
        schema:
          type: string
          title: Tool Id
          example: search-data
      - name: draft
        in: query
        required: false
        description: Set to true to call the draft version of the asset.
        schema:
          type: boolean
          default: false
          title: Draft
          example: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  additionalProperties: true
                - type: string
                title: Response 200 Postmcpservertoolresponse
              examples:
                searchDataResponse:
                  summary: search-data response example
                  value:
                    search_result: '{"string": [{"id": "MCP_GETTING_STARTED.TEXT", "display_name": "Text", "record_display_name": "Mcp Getting Started", "column_type": "STRING", "entity_type": "Attribute"}]}'
                loadDataResponse:
                  summary: load-data response example
                  value:
                    page: 0
                    page_size: 50
                    total: 1
                    data_frame_content:
                      data:
                      - MCP_GETTING_STARTED.ID: '123'
                        MCP_GETTING_STARTED.TEXT: Sample result
                      schema:
                      - id: MCP_GETTING_STARTED.ID
                        type: STRING
                        displayName: Id
                      - id: MCP_GETTING_STARTED.TEXT
                        type: STRING
                        displayName: Text
        '404':
          description: Asset not found
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CelonisValidationError'
                title: Response 422 Postmcpservertoolresponse
components:
  schemas:
    CelonisValidationError:
      type: object
      title: CelonisValidationError
      description: Celonis frontend compatible validation error model.
      properties:
        error:
          type: string
          title: Error
        attribute:
          type: string
          title: Attribute
          default: ''
        errorCode:
          type: string
          title: Errorcode
          default: ''
        additionalInfo:
          type: string
          title: Additionalinfo
          default: ''
      required:
      - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: AppKey