api-schema.yml

openapi: 3.0.3
info:
  title: Dimagi Chatbots
  version: '1'
  description: Experiments with AI, GPT and LLMs
paths:
  /api/experiments/:
    get:
      operationId: experiment_list
      summary: List Experiments
      parameters:
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      tags:
      - Experiments
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExperimentList'
          description: ''
  /api/experiments/{id}/:
    get:
      operationId: experiment_retrieve
      summary: Retrieve Experiment
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - Experiments
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
          description: ''
  /api/files/{id}/content:
    get:
      operationId: file_content
      summary: Download File Content
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Files
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: ''
  /api/openai/{experiment_id}/chat/completions:
    post:
      operationId: openai_chat_completions
      description: |2

        Use OpenAI's client to send messages to the experiment and get responses. This will
        create a new session in the experiment with all the provided messages
        and return the response from the experiment.

        The last message must be a 'user' message.

        Example (Python):

        ```python
        experiment_id = "your experiment ID"

        client = OpenAI(
            api_key="your API key",
            base_url=f"https://chatbots.dimagi.com/api/openai/{experiment_id}",
        )

        completion = client.chat.completions.create(
            model="anything",
            messages=[
                {"role": "assistant", "content": "How can I help you today?"},
                {"role": "user", "content": "I need help with something."},
            ],
        )

        reply = completion.choices[0].message
        ```
      summary: Chat Completions API for Experiments
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - OpenAI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
        required: true
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
          description: ''
  /api/participants/:
    post:
      operationId: update_participant_data
      description: Upsert participant data for all specified experiments in the payload
      summary: Update Participant Data
      tags:
      - Participants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantDataUpdateRequest'
            examples:
              CreateParticipantData:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    data:
                      name: John
                  - experiment: exp2
                    data:
                      name: Doe
                    schedules:
                    - id: sched1
                      name: Schedule 1
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt 1
                summary: Create participant data for multiple experiments
              UpdateParticipantSchedules:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    schedules:
                    - id: sched1
                      name: Schedule 1 updated
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt updated
                    - id: sched2
                      delete: true
                summary: Update and delete participant schedules
        required: true
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          description: No response body
  /api/sessions/:
    get:
      operationId: session_list
      summary: List Experiment Sessions
      parameters:
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - in: query
        name: tags
        schema:
          type: string
        description: A list of session tags (comma separated) to filter the results
          by
      tags:
      - Experiment Sessions
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExperimentSessionList'
          description: ''
    post:
      operationId: session_create
      summary: Create Experiment Session
      tags:
      - Experiment Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperimentSessionCreate'
        required: true
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentSession'
          description: ''
  /api/sessions/{id}/:
    get:
      operationId: session_retrieve
      description: |2

        Retrieve the details of an session. This includes the messages exchanged during the session ordered
        by the creation date.
      summary: Retrieve Experiment Session
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentSessionWithMessages'
          description: ''
  /channels/api/{experiment_id}/incoming_message:
    post:
      operationId: new_api_message
      description: Chat with an experiment.
      summary: New API Message
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - Channels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewAPIMessage'
        required: true
      security:
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewAPIMessageResponse'
          description: ''
components:
  schemas:
    ChatCompletionResponseChoices:
      type: object
      properties:
        finish_reason:
          type: string
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatCompletionResponseMessage'
      required:
      - finish_reason
      - index
      - message
    ChatCompletionResponseMessage:
      type: object
      properties:
        role:
          $ref: '#/components/schemas/ChatCompletionResponseMessageRoleEnum'
        content:
          type: string
      required:
      - content
      - role
    ChatCompletionResponseMessageRoleEnum:
      enum:
      - assistant
      type: string
      description: '* `assistant` - assistant'
    CreateChatCompletionRequest:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
      - messages
    CreateChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionResponseChoices'
        created:
          type: integer
        model:
          type: string
        object:
          $ref: '#/components/schemas/ObjectEnum'
      required:
      - choices
      - created
      - id
      - model
      - object
    Experiment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 128
        url:
          type: string
          format: uri
          readOnly: true
          title: API URL
        version_number:
          type: integer
          maximum: 2147483647
          minimum: 0
      required:
      - id
      - name
      - url
    ExperimentSession:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          readOnly: true
        team:
          allOf:
          - $ref: '#/components/schemas/Team'
          readOnly: true
        experiment:
          allOf:
          - $ref: '#/components/schemas/Experiment'
          readOnly: true
        participant:
          allOf:
          - $ref: '#/components/schemas/Participant'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - created_at
      - experiment
      - id
      - participant
      - team
      - updated_at
      - url
    ExperimentSessionCreate:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        experiment:
          type: string
          format: uuid
          title: Experiment ID
        participant:
          type: string
          title: Participant identifier
          description: Channel specific participant identifier
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
      - experiment
      - url
    ExperimentSessionWithMessages:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          readOnly: true
        team:
          allOf:
          - $ref: '#/components/schemas/Team'
          readOnly: true
        experiment:
          allOf:
          - $ref: '#/components/schemas/Experiment'
          readOnly: true
        participant:
          allOf:
          - $ref: '#/components/schemas/Participant'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          readOnly: true
      required:
      - created_at
      - experiment
      - id
      - messages
      - participant
      - team
      - updated_at
      - url
    File:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
        content_type:
          type: string
        size:
          type: integer
        content_url:
          type: string
          format: uri
          readOnly: true
      required:
      - content_url
      - name
      - size
    Message:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        role:
          $ref: '#/components/schemas/MessageRoleEnum'
        content:
          type: string
        metadata:
          type: object
          additionalProperties: {}
          readOnly: true
          description: |2

            Metadata for the message. Currently documented keys:
              * `is_summary`: boolean, whether this message is a summary of the conversation to date. When this
                is true, the message will not be displayed in the chat interface but it will be used when
                generating the chat history for the LLM. The history will include all messages up to the last
                summary message (starting from the most recent message).
        tags:
          type: array
          items:
            type: string
          readOnly: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/File'
          readOnly: true
      required:
      - attachments
      - content
      - created_at
      - metadata
      - role
      - tags
    MessageRoleEnum:
      enum:
      - system
      - user
      - assistant
      type: string
      description: |-
        * `system` - system
        * `user` - user
        * `assistant` - assistant
    NewAPIMessage:
      type: object
      properties:
        message:
          type: string
          title: User message
        session:
          type: string
          title: Optional session ID
      required:
      - message
    NewAPIMessageResponse:
      type: object
      properties:
        response:
          type: string
          title: AI response
      required:
      - response
    ObjectEnum:
      enum:
      - chat.completion
      type: string
      description: '* `chat.completion` - chat.completion'
    PaginatedExperimentList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/Experiment'
    PaginatedExperimentSessionList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentSession'
    Participant:
      type: object
      properties:
        identifier:
          type: string
          maxLength: 320
    ParticipantDataUpdateRequest:
      type: object
      properties:
        identifier:
          type: string
          title: Participant Identifier
        name:
          type: string
          title: Participant Name
        platform:
          allOf:
          - $ref: '#/components/schemas/PlatformEnum'
          default: api
          title: Participant Platform
        data:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantExperimentData'
      required:
      - data
      - identifier
    ParticipantExperimentData:
      type: object
      properties:
        experiment:
          type: string
          format: uuid
          title: Experiment ID
        data:
          type: object
          additionalProperties: {}
          title: Participant Data
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantSchedule'
      required:
      - experiment
    ParticipantSchedule:
      type: object
      properties:
        id:
          type: string
          title: Schedule ID
          maxLength: 32
        name:
          type: string
          title: Schedule Name
        prompt:
          type: string
          title: Prompt to send to bot
        date:
          type: string
          format: date-time
          title: Schedule Date
        delete:
          type: boolean
          default: false
          title: Delete Schedule
    PlatformEnum:
      enum:
      - telegram
      - web
      - whatsapp
      - facebook
      - sureadhere
      - api
      - slack
      type: string
      description: |-
        * `telegram` - Telegram
        * `web` - Web
        * `whatsapp` - WhatsApp
        * `facebook` - Facebook
        * `sureadhere` - SureAdhere
        * `api` - API
        * `slack` - Slack
    Team:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        slug:
          type: string
          maxLength: 50
          pattern: ^[-a-zA-Z0-9_]+$
      required:
      - name
      - slug
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-api-key
    tokenAuth:
      type: http
      scheme: bearer