swagger.yaml

swagger: '2.0'
schemes:
  - http
host: localhost:8911
basePath: /api/v2
info:
  description: |
    # Introduction
    The Developer API allows our more advanced users to interact with Mix It Up using external or customized programs. To use this feature, ensure the Developer API is enabled on the Services page. All APIs are REST-like endpoints that you can perform calls receiving/using JSON text. All endpoints begin with the base address of http://localhost:8911/api/v2/
  version: '2.0.0'
  title: Mix It Up Developer API
produces:
  - application/json
consumes:
  - application/json
tags:
  - name: User
    description: Operations related to Mix It Up User data
  - name: Currency
    description: Operations related to Mix It Up Currency data
  - name: Chat
    description: Operations related to Mix It Up Chat
  - name: Commands
    description: Operations related to Mix It Up Commands
  - name: Inventory
    description: Operations related to Mix It Up Inventory data

paths:
  '/users/{userId}':
    parameters:
      - name: userId
        in: path
        description: 'The Mix It Up user ID that needs to be fetched'
        required: true
        type: string
        format: uuid
    get:
      tags:
        - User
      summary: Get user data by Mix It Up user ID
      operationId: userId
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/MixItUpUser'
        '404':
          description: User not found
          schema:
            $ref: '#/definitions/Error'

  '/users/{platform}/{usernameOrID}':
    parameters:
      - name: platform
        in: path
        description: 'The name of the streaming platform (EX: Twitch, YouTube, etc.)'
        required: true
        type: string
      - name: usernameOrID
        in: path
        description: 'The platform username or ID that needs to be fetched'
        required: true
        type: string
    get:
      tags:
        - User
      summary: Get user data by platform username or ID
      operationId: getPlatformUserByUsernameOrID
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/MixItUpUser'
        '404':
          description: User not found
          schema:
            $ref: '#/definitions/Error'

  '/users':
    parameters:
      - name: skip
        in: query
        description: 'How many users to skip'
        required: true
        type: string
      - name: pageSize
        in: query
        description: 'The total number of users to return'
        required: true
        type: string
    get:
      summary: This API can be used to lookup multiple users at once.
      tags:
        - User
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpUsers'
        '400':
          description: Bad request was sent in
          schema:
            $ref: '#/definitions/Error'

  '/users/active':
    parameters:
      - name: skip
        in: query
        description: 'How many users to skip'
        required: true
        type: string
      - name: pageSize
        in: query
        description: 'The total number of users to return'
        required: true
        type: string
    get:
      summary: This API can be used to lookup multiple active users at once.
      tags:
        - User
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpUsers'
        '400':
          description: Bad request was sent in
          schema:
            $ref: '#/definitions/Error'

  '/currency':
    get:
      tags:
        - Currency
      summary: Gets a list of all currencies available.
      operationId: getAllCurrencies
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpCurrency'

  '/currency/{currencyId}/{userId}':
    parameters:
      - name: currencyId
        in: path
        description: 'The currency ID to query'
        required: true
        type: string
        format: uuid
      - name: userId
        in: path
        description: 'The Mix It Up user ID to query for'
        required: true
        type: string
        format: uuid
    get:
      tags:
        - Currency
      summary: Gets the currency amount for a specific user
      operationId: getCurrencyById
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The currency could not be found.
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - Currency
      summary: Updates the currency amount for a specific user
      operationId: patchCurrencyById
      parameters:
        - name: updateAmount
          description: 'The amount to update the currency by'
          in: body
          required: true
          schema:
           $ref: '#/definitions/UpdateCurrencyAmount'
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The currency could not be found.
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - Currency
      summary: Set the currency amount for a specific user
      operationId: putCurrencyById
      parameters:
        - name: updateAmount
          description: 'The amount to set the currency to'
          in: body
          required: true
          schema:
           $ref: '#/definitions/UpdateCurrencyAmount'
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The currency could not be found.
          schema:
            $ref: '#/definitions/Error'

  '/chat/message':
    post:
      tags:
        - Chat
      summary: Sends a message to the chat
      operationId: sendChatMessage
      parameters:
        - name: chatMessage
          description: 'The chat message to send'
          in: body
          required: true
          schema:
           $ref: '#/definitions/MixItUpChatMessage'
      produces:
        - application/json
      responses:
        '200':
          description: Success
        '400':
          description: Bad request was sent in
          schema:
            $ref: '#/definitions/Error'

  '/chat/clear':
    post:
      tags:
        - Chat
      summary: Clears the chat for all connected platforms
      operationId: clearChat
      produces:
        - application/json
      responses:
        '200':
          description: Success
        '400':
          description: Bad request was sent in
          schema:
            $ref: '#/definitions/Error'

  '/commands':
    get:
      parameters:
      - name: skip
        in: query
        description: 'How many commands to skip'
        required: true
        type: string
      - name: pageSize
        in: query
        description: 'The total number of commands to return'
        required: true
        type: string
      tags:
        - Commands
      summary: Gets a list of all commands available.
      operationId: getAllCommands
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpCommands'
            
  '/commands/{commandId}':
    parameters:
      - name: commandId
        in: path
        description: 'The command ID to query'
        required: true
        type: string
        format: uuid
    get:
      tags:
        - Commands
      summary: Gets the requested command.
      operationId: getCommand
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/MixItUpCommand'
        '404':
          description: The command could not be found.
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - Commands
      summary: Used to run the requested command.
      operationId: runCommand
      parameters:
        - name: parameters
          description: 'The parameters to run the command'
          in: body
          required: true
          schema:
           $ref: '#/definitions/MixItUpCommandParameters'
      produces:
        - application/json
      responses:
        '200':
          description: Success
        '404':
          description: The command could not be found.
          schema:
            $ref: '#/definitions/Error'
                   
  '/commands/{commandId}/state/{state}':
    parameters:
      - name: commandId
        in: path
        description: 'The command ID to query'
        required: true
        type: string
        format: uuid
      - name: state
        in: path
        description: 'The state to update the command to (0 = Disabled, 1 = Enabled, 2 = Toggle)'
        required: true
        type: integer
    patch:
      tags:
        - Commands
      summary: Updates the command's state'.
      operationId: updateCommandState
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/MixItUpCommand'
        '404':
          description: The command could not be found.
          schema:
            $ref: '#/definitions/Error'

  '/inventory':
    get:
      tags:
        - Inventory
      summary: Gets a list of all inventories available.
      operationId: getAllInventories
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpInventory'

  '/inventory/{inventoryId}/{userId}':
    parameters:
      - name: inventoryId
        in: path
        description: 'The inventory ID to query'
        required: true
        type: string
        format: uuid
      - name: userId
        in: path
        description: 'The Mix It Up user ID to query'
        required: true
        type: string
        format: uuid
    get:
      tags:
        - Inventory
      summary: Gets a specific inventory for a specific user
      operationId: getInventoryById
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ListOfMixItUpInventoryItemAmount'
        '404':
          description: The inventory could not be found.
          schema:
            $ref: '#/definitions/Error'

  '/inventory/{inventoryId}/{itemId}/{userId}':
    parameters:
      - name: inventoryId
        in: path
        description: 'The inventory ID to query'
        required: true
        type: string
        format: uuid
      - name: itemId
        in: path
        description: 'The inventory item ID to query'
        required: true
        type: string
        format: uuid
      - name: userId
        in: path
        description: 'The Mix It Up user ID to query for'
        required: true
        type: string
        format: uuid
    get:
      tags:
        - Inventory
      summary: Gets the inventory item amount for a specific user
      operationId: getInventoryItemById
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The inventory item could not be found.
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - Inventory
      summary: Updates the inventory item amount for a specific user
      operationId: patchInventoryItemById
      parameters:
        - name: updateAmount
          description: 'The amount to update the inventory item by'
          in: body
          required: true
          schema:
           $ref: '#/definitions/UpdateInventoryAmount'
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The inventory item could not be found.
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - Inventory
      summary: Set the inventory item amount for a specific user
      operationId: putInventoryById
      parameters:
        - name: updateAmount
          description: 'The amount to set the inventory item to'
          in: body
          required: true
          schema:
           $ref: '#/definitions/UpdateInventoryAmount'
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: integer
        '404':
          description: The inventory item could not be found.
          schema:
            $ref: '#/definitions/Error'
          
  '/status/version':
    get:
      tags:
        - Status
      summary: Gets the Mix It Up version number
      operationId: statusVersion
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            type: string
            example: 1.0.0.0
        '400':
          description: Bad request was sent in
          schema:
            $ref: '#/definitions/Error'


definitions:
  MixItUpUser:
    type: object
    required: [ ID ]
    properties:
      ID:
        description: The Mix It Up User ID.
        type: string
        format: uuid
        example: 137CD793-F4E7-4330-8282-B06E52644F78
      PlatformData:
        type: object
        additionalProperties:
            $ref: '#/definitions/MixItUpPlatformUser'
      LastActivity:
        description: The last date time of activity.
        type: string
      LastUpdated:
        description: The last date time of updates.
        type: string
      OnlineViewingMinutes:
        description: The total number of online viewing minutes in your stream.
        type: integer
        example: 1234567890
      CustomTitle:
        description: The user's custom title.
        type: string
        example: Ultimate
      IsSpecialtyExcluded:
        description: Whether the user is a specialty excluded user.
        type: boolean
        example: false
      Notes:
        description: The notes for the user.
        type: string
        example: Is a lovely person
      CurrencyAmounts:
        type: object
        additionalProperties:
          type: integer
      InventoryAmounts:
        type: object
        additionalProperties:
          type: object
          additionalProperties:
            type: integer
      StreamPassAmounts:
        type: object
        additionalProperties:
          type: integer

  MixItUpPlatformUser:
    type: object
    required: [ ID, ViewingMinutes, CurrencyAmounts ]
    properties:
      Platform:
        description: The Platform name.
        type: string
        example: Twitch
      ID:
        description: The Platform user ID.
        type: string
        example: 1234567890
      Username:
        description: The Platform username.
        type: string
        example: saviorxtanren
      DisplayName:
        description: The Platform display name.
        type: string
        example: SaviorXTanren
      AvatarLink:
        description: The Platform avatar URL.
        type: string
      SubscriberBadgeLink:
        description: The Platform subscriber badge URL.
        type: string
      RoleBadgeLink:
        description: The Platform role badge URL.
        type: string
      SpecialtyBadgeLink:
        description: The Platform specialty badge URL.
        type: string
      Roles:
        type: array
        description: The list of Platform roles.
        items:
          type: string
      AccountDate:
        description: The platform account date.
        type: string
      FollowDate:
        description: The platform follow date.
        type: string
      SubscribeDate:
        description: The platform subscriber date.
        type: string
      SubscriberTier:
        description: The platform subscriber tier.
        type: integer

  ListOfMixItUpUsers:
    type: array
    items:
      $ref: '#/definitions/MixItUpUser'

  UpdateCurrencyAmount:
    type: object
    required: [ Amount ]
    properties:
      Amount:
        description: The amount to adjust the user's currency.  This amount may be positive or negative.
        type: integer

  MixItUpCurrency:
    type: object
    required: [ ID, Name ]
    properties:
      ID:
        description: The Mix It Up currency ID.
        type: string
        format: uuid
        example: 1783e5d9-c2ab-423a-ae64-7dc9a086b194
      Name:
        description: The Mix It Up currency name.
        type: string
        example: Influence

  ListOfMixItUpCurrency:
    type: array
    items:
      $ref: '#/definitions/MixItUpCurrency'

  UpdateInventoryAmount:
    type: object
    required: [ Amount ]
    properties:
      Amount:
        description: The amount to adjust the user's inventory item.  This amount may be positive or negative.
        type: integer

  MixItUpInventoryItemAmount:
    type: object
    required: [ ID, Name, Items ]
    properties:
      ID:
        description: The Mix It Up inventory item ID.
        type: string
        format: uuid
      Name:
        description: The Mix It Up inventory item name.
        type: string
        example: Influence
      Amount:
        description: The amount of this item the user has.
        type: integer
        example: 2751

  ListOfMixItUpInventoryItemAmount:
    type: array
    items:
      $ref: '#/definitions/MixItUpInventoryItemAmount'

  MixItUpInventoryItem:
    type: object
    required: [ ID, Name ]
    properties:
      ID:
        description: The Mix It Up inventory item ID.
        type: string
        format: uuid
        example: 1783e5d9-c2ab-423a-ae64-7dc9a086b194
      Name:
        description: The Mix It Up inventory item name.
        type: string
        example: Influence

  MixItUpInventory:
    type: object
    required: [ ID, Name ]
    properties:
      ID:
        description: The Mix It Up inventory ID.
        type: string
        format: uuid
        example: 1783e5d9-c2ab-423a-ae64-7dc9a086b194
      Name:
        description: The Mix It Up inventory name.
        type: string
        example: Equipment
      Items:
        type: array
        items:
          $ref: '#/definitions/MixItUpInventoryItem'

  ListOfMixItUpInventory:
    type: array
    items:
      $ref: '#/definitions/MixItUpInventory'
      
  MixItUpCommand:
    required: [ ID, Name, IsEnabled, Category ]
    type: object
    properties:
      ID:
        description: The Mix It Up command ID.
        type: string
        format: uuid
        example: 1783e5d9-c2ab-423a-ae64-7dc9a086b194
      Name:
        description: The Mix It Up command name.
        type: string
      Type:
        description: The Mix It Up command type.
        type: string
      IsEnabled:
        description: True if enabled, false otherwise
        type: boolean
      Unlocked:
        description: Whether the command is unlocked or not.
        type: boolean
      GroupName:
        description: The name of the group the command belongs to, if any.
        type: string

  ListOfMixItUpCommands:
    type: array
    items:
      $ref: '#/definitions/MixItUpCommand'

  MixItUpCommandParameters:
    type: object
    properties:
      Platform:
        description: The streaming platform to send the message to.
        type: string
        example: Twitch
      Arguments:
        description: The arguments for the command.
        type: string

  MixItUpChatMessage:
    required: [ Message ]
    type: object
    properties:
      Message:
        description: The message to send to chat.
        type: string
        example: This is a test of the emergency broadcast system!
      Platform:
        description: The streaming platform to send the message to.
        type: string
        example: Twitch
      SendAsStreamer:
        description: True will force the message to send as the streamer. False will try to send as the registered bot, if available.
        type: boolean
        example: false
        default: false

  Error:
    type: object
    required: [ Message ]
    properties:
      Message:
        description: "A description of the problem."
        type: string