openapi: 3.2.0
info:
  title: Elemental Machines Machines Usage API
  description: Documentation for using Elemental Machines API. To start, get an access token using /oauth/token.
  version: '1.0'
  contact:
    email: help@elementalmachines.io
servers:
- url: https://api.elementalmachines.io
  description: Elemental Machines production API
security:
- access_token: []
tags:
- name: Machines Usage
paths:
  /api/machines/usage/aggregated.json:
    get:
      tags:
      - Machines Usage
      summary: Get aggregated utilization information for all machines under a customer group
      operationId: machinesUsageAggregated
      parameters:
      - name: access_token
        in: query
        description: Access token
        required: true
        schema:
          type: string
      - name: customer_group_uuid
        in: query
        description: Customer group UUID
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        required: true
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of results per page
        required: true
        schema:
          type: integer
          default: 10
      - name: time_zone
        in: query
        description: Time zone string. Default to user time zone if not specified.
        required: false
        schema:
          type: string
      - name: start_work_hour
        in: query
        description: Start work hour, integer 0~23. Default work hours to all 24 hours if not specified.
        required: false
        schema:
          type: integer
      - name: end_work_hour
        in: query
        description: End work hour, integer 0~23. Default work hours to all 24 hours if not specified.
        required: false
        schema:
          type: integer
      - name: work_days[]
        in: query
        description: Work day (1~7 representing mon~sun). Enter single parameter text value in this form (e.g. 3). Default to all 7 days if not specified. For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: start_date
        in: query
        description: Start date of the requested date range, default date range is last 30 days (e.g. 2022-05-31). If start_date is specified, end_date will become required.
        required: false
        schema:
          type: string
          default: '2026-06-28'
      - name: end_date
        in: query
        description: End date of the requested date range, default date range is last 30 days (e.g. 2022-06-07). If end_date is specified, start_date will become required.
        required: false
        schema:
          type: string
          default: '2026-07-28'
      - name: location_tags[]
        in: query
        description: Location tag filter. Enter single parameter text value in this form (e.g. Lab 24).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: equipment_category_tags[]
        in: query
        description: Equipment category tag filter. Enter single parameter text value in this form (e.g. Centrifuge).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: machine_uuids[]
        in: query
        description: Machine UUID filter.  Enter single parameter text value in this form (e.g. 454d60e3-05c3-4356-872e-fbd480fe91fa).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sort_by
        in: query
        description: One of equipment_name, most_used [most_used is default]
        required: false
        schema:
          type: string
      - name: sort_direction
        in: query
        description: asc or desc [asc is default]
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
      security:
      - access_token: []
  /api/machines/usage/hourly.json:
    get:
      tags:
      - Machines Usage
      summary: Get hourly utilization information for all machines under a customer group
      operationId: machinesUsageHourly
      parameters:
      - name: access_token
        in: query
        description: Access token
        required: true
        schema:
          type: string
      - name: customer_group_uuid
        in: query
        description: Customer group UUID
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        required: true
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of results per page
        required: true
        schema:
          type: integer
          default: 10
      - name: time_zone
        in: query
        description: Time zone string. Default to user time zone if not specified.
        required: false
        schema:
          type: string
      - name: start_work_hour
        in: query
        description: Start work hour, integer 0~23. Default work hours to all 24 hours if not specified.
        required: false
        schema:
          type: integer
      - name: end_work_hour
        in: query
        description: End work hour, integer 0~23. Default work hours to all 24 hours if not specified.
        required: false
        schema:
          type: integer
      - name: work_days[]
        in: query
        description: Work day (1~7 representing mon~sun). Enter single parameter text value in this form (e.g. 3). Default to all 7 days if not specified. For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: start_date
        in: query
        description: Start date of the requested date range, default date range is last 30 days (e.g. 2022-05-31). If start_date is specified, end_date will become required.
        required: false
        schema:
          type: string
          default: '2026-07-27'
      - name: end_date
        in: query
        description: End date of the requested date range, default date range is last 30 days (e.g. 2022-06-07). If end_date is specified, start_date will become required.
        required: false
        schema:
          type: string
          default: '2026-07-28'
      - name: location_tags[]
        in: query
        description: Location tag filter. Enter single parameter text value in this form (e.g. Lab 24).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: equipment_category_tags[]
        in: query
        description: Equipment category tag filter. Enter single parameter text value in this form (e.g. Centrifuge).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: machine_uuids[]
        in: query
        description: Machine UUID filter.  Enter single parameter text value in this form (e.g. 454d60e3-05c3-4356-872e-fbd480fe91fa).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sort_by
        in: query
        description: One of equipment_name, most_used [most_used is default]
        required: false
        schema:
          type: string
      - name: sort_direction
        in: query
        description: asc or desc [asc is default]
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
      security:
      - access_token: []
  /api/machines/usage/status.json:
    get:
      tags:
      - Machines Usage
      summary: Get the usage statuses for all machines under a customer group
      operationId: machinesUsageStatus
      parameters:
      - name: access_token
        in: query
        description: Access token
        required: true
        schema:
          type: string
      - name: customer_group_uuid
        in: query
        description: Customer group UUID
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        required: true
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of results per page
        required: true
        schema:
          type: integer
          default: 10
      - name: location_tags[]
        in: query
        description: Location tag filter. Enter single parameter text value in this form (e.g. Lab 24).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: equipment_category_tags[]
        in: query
        description: Equipment category tag filter. Enter single parameter text value in this form (e.g. Centrifuge).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: machine_uuids[]
        in: query
        description: Machine UUID filter.  Enter single parameter text value in this form (e.g. 454d60e3-05c3-4356-872e-fbd480fe91fa).  For help on multiple values, contact Customer Support.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sort_by
        in: query
        description: One of equipment_name, eq_category, location, availability [availability is default]
        required: false
        schema:
          type: string
      - name: sort_direction
        in: query
        description: asc or desc [asc is default]
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
      security:
      - access_token: []
components:
  securitySchemes:
    access_token:
      type: apiKey
      in: query
      name: access_token
      description: OAuth 2.0 access token passed as the access_token query parameter. Obtain one from POST /oauth/token (Resource Owner Password Credentials grant).
    oauth2_password:
      type: oauth2
      description: Resource Owner Password Credentials grant. Documented in the provider's Swagger 1.2 declaration at /docs/api/oauth.json.
      flows:
        password:
          tokenUrl: https://api.elementalmachines.io/oauth/token
          scopes: {}