Celonis AI Agent API

openapi: 3.0.0
info:
  title: OpenAPI Specification
  description: AI API to chat with Celonis Agents and run their tools.
  x-audience: EX
  version: v1.2.0
security:
  - BearerAuth: []
  - ApiKeyAuth: []
servers:
  - url: https://30f873b4-88d4-49ba-b327-6f651d7b99e6.remockly.com
paths:
  /intelligence/api/ai/agents/{agent_id}/conversations:
    post:
      tags:
        - Agents - Conversation
      operationId: pushConversations
      summary: Post Conversation Message
      description: >-
        Posts a conversation message to an asset, optionally with a conversation
        id.

        Always returns a text response for external use cases.
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            example: agent
      requestBody:
        description: Message details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: Return agent id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/DefaultResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: AppKey
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: >
            A URI reference that uniquely identifies the problem type only in
            the context of the provided API. Opposed to the specification in
            RFC-7807, it is not recommended that it be dereferenceable and point
            to a human-readable documentation or be globally unique for the
            problem type.
          default: about:blank
          example: /some/uri-reference
        title:
          type: string
          description: >
            A short summary of the problem type. Written in English and readable
            for engineers. Usually not suited for non technical stakeholders and
            not localized.
          example: some title for the error situation
        status:
          type: integer
          format: int32
          description: >
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
        detail:
          type: string
          description: >
            A human readable explanation specific to this occurrence of the
            problem that is helpful to locate the problem and give advice on how
            to proceed. Written in English and readable for engineers. Usually
            not suited for non technical stakeholders and not localized.
          example: some description for the error situation
        instance:
          type: string
          format: uri-reference
          description: >
            A URI reference that identifies the specific occurrence of the
            problem, e.g. by adding a fragment identifier or sub-path to the
            problem type. May be used to locate the root of this problem in the
            source code.
          example: /some/uri-reference#specific-occurrence-context
    ChatResponse:
      title: ChatResponse
      description: Hits conversations of an specific agent
      type: object
      properties:
        conversationId:
          type: string
          description: Conversation identifier
          example: abc-def-ghi-etc
        text:
          type: string
          description: Text from Chat
          example: this is an example
        structuredOutput:
          type: object
          additionalProperties: true
          nullable: true
          description: >
            This field is intended for machine-to-machine communication. The
            structure  is dynamic and defined by the JSON schema configured
            within the specific  agent’s settings. This field will only be
            present if a schema is defined  for the agent and the LLM
            successfully populates it based on the  conversation context. If no
            schema is configured, or if the agent provides  a purely
            conversational response, this field will be omitted.
    Message:
      title: Message chat
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        conversationId:
          type: string
      required:
        - message
  responses:
    BadRequest:
      description: Bad Request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Unauthorized access.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Forbidden.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: The specified resource was not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: Conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    TooManyRequests:
      description: Too Many Requests.
      headers:
        X-RateLimit-Limit:
          description: Request limit per hour.
          schema:
            type: integer
            format: int32
        X-RateLimit-Remaining:
          description: The number of requests left for the time window.
          schema:
            type: integer
            format: int32
        X-RateLimit-Reset:
          description: The UTC date/time at which the current rate limit window resets.
          schema:
            type: string
            format: date-time
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: Internal Server Error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: Service Unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    DefaultResponse:
      description: Default error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'