openapi: "3.0.3"
info:
  title: "License Server API"
  description: API to query current token usage.
  contact:
    name: Threedy GmbH
    url: https://www.threedy.io/
    email: contact@threedy.io
  version: "3.6.0"
servers:
  - url: '{server}'
    variables:
      server:
        default: http://license.threedy.io:8200  # Demo Server
paths:
  /usage/export:
    get:
      description: Used to export raw usage information from which token usage can be calculated.
      tags:
        - Export
      parameters:
        - in: query
          name: start
          required: false
          schema:
            type: integer
          description: Optional unix timestamp defining start range of export data.
        - in: query
          name: end
          required: false
          schema:
            type: integer
          description: Optional unix timestamp defining end range of export data.
      responses:
        '200':
          description: Success. The body contains a zip file.
          content:
            'application/zip':
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: Attachment and filename of the result file (i3dh-usage-export.zip).
              schema:
                type: string
        '500':
          description: An internal error occurred.
          content:
            'text/plain':
              example: "failed to create: ..."
        '400':
          description: The incoming request was malformed. Body contains details.
          content:
            'text/plain':
              example: "failed to parse end as unix: ..."
  /usage/summary:
    get:
      description: Usage summary detailing license information and current token usage.
      tags:
        - Summary
      responses:
        '200':
          description: Success. The body contains usage information.
          content:
            'application/json':
              example:
                start: "2023-01-01T00:00:00Z"
                end: "2024-01-01T00:00:00Z"
                entitled: 500000
                used: 250000
                numCurrentUsers: 10
              schema:
                $ref: "#/components/schemas/Summary"
        '500':
          description: An internal error occurred.
          content:
            'application/json':
              example:
                error:
                  code: 500
                  msg: "failed to get usage summary: ..."
  /usage/summary/{interval}:
    get:
      description: Usage summary detailing license information and current usage grouped by month, week or day.
      tags:
        - Summary
      parameters:
        - in: path
          required: true
          name: interval
          schema:
            $ref: "#components/schemas/Interval"
      responses:
        '200':
          description: Success. The body contains grouped usage information.
          content:
            'application/json':
              example:
                start: "2023-01-01T00:00:00Z"
                end: "2024-01-01T00:00:00Z"
                entitled: 500000
                used: 250000
                numCurrentUsers: 10
                instances:
                  - date: "2023-01-01T00:00:00+01:00"
                    count: 100
                  - date: "2023-02-01T00:00:00+01:00"
                    count: 200
                  - date: "2023-03-01T00:00:00+01:00"
                    count: 300
              schema:
                $ref: "#/components/schemas/Summary"
        '500':
          description: An internal error occurred.
          content:
            'text/plain':
              example: "failed to get usage summary: ..."

tags:
  - name: Export
  - name: Summary

components:
  schemas:
    Summary:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Timestamp from which the current license is valid.
        end:
          type: string
          format: date-time
          description: Timestamp until which the current license is valid.
        entitled:
          type: integer
          description: Number of tokens the current license grants.
        used:
          type: integer
          description: Number of tokens already used.
        numCurrentUsers:
          type: integer
          description: Number of active sessions within the last few minutes.
        instances:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
                description: Starting date for which the given count number of tokens was used. Interval is until start date of next entry.
              count:
                type: integer
                description: Number of tokens used for the given date.
    Interval:
      type: string
      enum: [ day, week, month ]
      description: Possible interval to query usage summary info.