Emporix AI Completions API

openapi: 3.2.0
info:
  title: Emporix AI Completions API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged AI Completions across 2 of this provider''s published API definitions: emporix-ai-service-openapi.yml, emporix-ai-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: AI Completions
  description: AI Completions
paths:
  /ai-service/{tenant}/completions:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    post:
      summary: Generating AI Completions
      operationId: POST-ai-completions
      responses:
        '200':
          $ref: '#/components/responses/200_resp_GET_text_generation'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
        '500':
          $ref: '#/components/responses/500_resp_common'
      description: 'Generates a completion based on chat history.

        Currently, the supported AI engine for the text generation is https://platform.openai.com/.


        ***

        Prerequisite: Using the AI service requires an API token, you have to either configure your own OpenAI account, or use the Emporix one. To configure your own OpenAI token, use the configuration service by storing the token under the `openAiApiToken` key.


        If you don''t provide your own OpenAI token, the Emporix one is used with the following limits: 3 mln input tokens and 1 mln output tokens. When you reach the limit, the next requests are rejected and you have to provide your own OpenAI token.

        Emporix uses the gpt-4o-mini model by default. If you want to use your own OpenAI account with a different AI model, please contact our Emporix Support Team to negotiate the model and usage.'
      security:
      - OAuth2:
        - ai.completion_manage
      requestBody:
        $ref: '#/components/requestBodies/Completion'
      tags:
      - AI Completions
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
        type:
          type: string
        message:
          type: string
        moreInfo:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              type:
                type: string
              message:
                type: string
              moreInfo:
                type: string
      description: ''
    GenerationResponse:
      title: GenerationResponse
      type: object
      description: Object represents the text generation response.
      properties:
        id:
          type: string
          description: 'Identifier of the text generation request. The value is populated only if the ID was provided in the request. '
        result:
          type: string
          description: Text generation result.
    CompletionRequest:
      title: CompletionRequest
      type: object
      required:
      - messages
      properties:
        id:
          type: string
          description: Identifier of the request. The value is not mandatory - if provided, then the ID is returned in the text generation response.
        messages:
          type: array
          items:
            type: object
            required:
            - role
            - content
            properties:
              role:
                type: string
                enum:
                - USER
                - SYSTEM
                - ASSISTANT
                description: Specifies the role of the message. `SYSTEM` - Provides instructions or context to the AI about the conversation. `USER` - Represents a message sent by the user. `ASSISTANT` - Represents a message generated by the AI.
              content:
                type: string
                description: Content of the message. Depending on the role parameter, it can be a background instruction, user instruction, or AI response.
    ErrorMessageFault:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
            detail:
              type: object
              properties:
                errorcode:
                  type: string
  responses:
    403_resp_common:
      description: Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Access forbidden:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    401_resp_common:
      description: The authorization token is invalid or has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageFault'
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    400_resp_common:
      description: The request was syntactically incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Code must not be null:
              value:
                code: 400
                status: Bad Request
                message: Validation problem with request body.
                details:
                - message: code must not be null nor blank
    500_resp_common:
      description: A server-side error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Internal Server Error:
              value:
                code: 500
                status: Internal Server Error
                message: Problem encountered while trying to connect to the database.
    200_resp_GET_text_generation:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationResponse'
          examples:
            Text Generation Response:
              value:
                id: en
                result: Mini pipe cutters are small cutting tools that are designed to precisely and effectively cut through pipes ranging in size from 3 to 16 millimeters. Unlike some larger pipe cutters, these mini versions are conveniently small and light enough to be carried around easily and used in places where a standard-sized cutter may not be able to fit. They are typically made of hardened steel and are designed to work on most types of tubing and thin-walled plastic piping. The continuous interlocking jaws hold the pipe securely while the cutting blade smoothly and accurately creates a precise and neat cutting edge. Mini pipe cutters are the perfect tool for plumbers and those tackling smaller scale pipe work in hard-to-reach places.
  parameters:
    path_tenant:
      name: tenant
      in: path
      required: true
      schema:
        type: string
      description: 'Your Emporix tenant name.


        **Note**: The tenant name should always be provided in lowercase.

        '
  requestBodies:
    Completion:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CompletionRequest'
          examples:
            Completion request:
              value:
                id: abc-123
                messages:
                - role: SYSTEM
                  content: You are an assistant responsible for creating a configuration based on information provided by user.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            ai.text_manage: Needed to execute actions related to the text generation.
            ai.completion_manage: Needed to execute actions related to the AI completions.
            ai.agentexecution_manage: Needed to execute agentic chat.
            ai.agentexecution_manage_own: Needed to execute agentic chat by customers.
            ai.agent_read: Needed to read AI agents.
            ai.agent_manage: Needed to manage AI agents.
          tokenUrl: https://api.emporix.io/oauth/token
x-refined-from:
- emporix-ai-service-openapi.yml
- emporix-ai-service-openapi.yml