openapi.yaml

---
openapi: 3.0.0
info:
  version: 1.0.0
  title: AstroPlant API
servers:
  - url: https://api.astroplant.sda-projects.nl
tags:
    - name: access
      description: Authentication and authorization endpoints.
    - name: definitions
      description: Endpoints to get information about definitions such as quantity types.
    - name: kits
      description: Endpoints to get or change information about kits.
    - name: kitRpc
      description: Endpoints to invoke remote procedure calls on kits.
    - name: users
      description: Endpoints to get or change information about users.
    - name: server
      description: Endpoints for getting information about the API server.
paths:
  "/version":
    get:
      summary: Grab the version of the API.
      tags:
        - server
      parameters: []
      responses:
        '200':
          description: The version of the API.
          content:
            "application/json":
              schema:
                type: string
                example: 1.0.0
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/time":
    get:
      summary: Get the current server time.
      tags:
        - server
      parameters: []
      responses:
        '200':
          description: An RFC3339 and ISO 8601 date and time string.
          content:
            "application/json":
              schema:
                type: string
                # format: "date-time"
                example: "2019-08-18T15:30:28+00:00"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits":
    get:
      summary: List all kits set to be shown on the public map.
      operationId: listKits
      tags:
        - kits
      parameters:
        - in: query
          name: lastSeenSince
          schema:
            type: string
            format: date-time
          description: Fetch all kits that have been seen after the given date and time.
        - in: query
          name: after
          schema:
            type: integer
          description: Fetch all kits after the given identifier.
      responses:
        '200':
          description: A paged array of kits.
          headers:
            x-next:
              $ref: "#/components/headers/CursorPaging"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kits"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    post:
      summary: Create a kit.
      operationId: createKit
      security:
        - bearerAuth: []
      tags:
        - kits
      requestBody:
        description: The kit to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewKit"
      responses:
        '201':
          description: The created kit.
          headers:
            Location:
              description: A link to the created kit.
              required: false
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                  - kitSerial
                  - password
                properties:
                  kitSerial:
                    type: string
                  password:
                    type: string
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}":
    get:
      summary: Info for a specific kit.
      operationId: showKitBySerial
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: The retrieved kit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kit"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    delete:
      summary: Delete a kit.
      operationId: deleteKit
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to patch.
          schema:
            type: string
      responses:
        '200':
          description: The kit was successfully deleted.
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    patch:
      summary: Update the kit details.
      operationId: patchKit
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to patch.
          schema:
            type: string
      requestBody:
        description: The kit patch.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchKit"
      responses:
        '200':
          description: The patched kit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kit"
                type: object
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/password":
    post:
      summary: Reset the kit's password.
      operationId: resetPassword
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to reset the password for.
          schema:
            type: string
      responses:
        '200':
          description: The kit's new password.
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/members":
    get:
      summary: Members of a specific kit.
      operationId: getKitMembers
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to get the members of.
          schema:
            type: string
      responses:
        '200':
          description: The kit's members.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/KitMembership"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    post:
      summary: Add a membership to a kit.
      operationId: addKitMember
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to add a membership to.
          schema:
            type: string
      requestBody:
        description: The membership to add.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewKitMembership"
      responses:
        '200':
          description: The kit's members.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitMembership"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/member-suggestions":
    get:
      summary: Suggestions of users to add to a kit.
      operationId: getKitMemberSuggestions
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to get the members of.
          schema:
            type: string
        - name: username
          in: query
          required: true
          description: (Part of) a username. Suggestions are limited to users with a similar username.
          schema:
            type: string
      responses:
        '200':
          description: Suggestions of users to add to the kit.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kit-memberships/{kitMembershipId}":
    patch:
      summary: Patch the kit membership.
      operationId: patchKitMembership
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitMembershipId
          in: path
          required: true
          description: The id of the kit membership to patch.
          schema:
            type: number
      requestBody:
        description: The kit membership patch.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchKitMembership"
      responses:
        '200':
          description: The updated kit membership.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitMembership"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    delete:
      summary: Delete the kit membership.
      operationId: deleteKitMembership
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitMembershipId
          in: path
          required: true
          description: The id of the kit membership to delete.
          schema:
            type: number
      responses:
        '200':
          description: The kit membership was successfully deleted.
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/aggregate-measurements":
    get:
      summary: Aggregate measurements made by a kit.
      operationId: listAggregateMeasurements
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to retrieve aggregate measurements for.
          schema:
            type: string
        - name: configuration
          in: query
          required: false
          description: An ID of a kit configuration to filter on. If not given, does not filter on kit configurations.
          schema:
            type: number
        - name: peripheral
          in: query
          required: false
          description: An ID of a peripheral to filter on. If not given, does not filter on peripherals.
          schema:
            type: number
        - name: quantityType
          in: query
          required: false
          description: An ID of a quantity type to filter on. If not given, does not filter on quantity types.
          schema:
            type: number
        - name: cursor
          in: query
          required: false
          description: A cursor for paging. Although this cursor can be constructed by the client (it is the url-encoding of the JSON-serialization of `[datetimeStart, id]` of the last measurement of the current page), this is discouraged. Instead, the Link header in the response body should be used to retrieve the server-generated URI to the next page.
          schema:
            type: string
      responses:
        '200':
          description: The retrieved aggregate measurements.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AggregateMeasurement"
          headers:
            Link:
              $ref: "#/components/headers/Link"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/archive":
    post:
      summary: Request permission to download a data archive of kit measurements.
      operationId: authorizeArchiveDownload
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to download a data archive of measurements for.
          schema:
            type: string
      responses:
        '200':
          description: A short-lived token.
          content:
            "*": {}
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    get:
      summary: Download a data archive of kit measurements.
      operationId: getArchiveContent
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to download a data archive of measurements for.
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: A token given by a POST request to '/kits/{kitSerial}/archive' prior to this request.
          schema:
            type: string
        - name: configuration
          in: query
          required: false
          description: An ID of a kit configuration to filter on. If not given, does not filter on kit configurations.
          schema:
            type: number
        - name: from
          in: query
          required: false
          description: A lower bound on date and time of measurements to include in the archive. If not given, does not filter on date and time.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: An upper bound on date and time of measurements to include in the archive. If not given, does not filter on date and time.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: The data archive content.
          content:
            "*": {}
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/media":
    get:
      summary: Media produced by a kit.
      operationId: listMedia
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to retrieve aggregate measurements for.
          schema:
            type: string
        - name: configuration
          in: query
          required: false
          description: An ID of a kit configuration to filter on. If not given, does not filter on kit configurations.
          schema:
            type: number
        - name: peripheral
          in: query
          required: false
          description: An ID of a peripheral to filter on. If not given, does not filter on peripherals.
          schema:
            type: number
        - name: cursor
          in: query
          required: false
          description: A cursor for paging. Although this cursor can be constructed by the client (it is the url-encoding of the JSON-serialization of `[datetime, id]` of the last media of the current page), this is discouraged. Instead, the Link header in the response body should be used to retrieve the server-generated URI to the next page.
          schema:
            type: string
      responses:
        '200':
          description: The retrieved media.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Media"
          headers:
            Link:
              $ref: "#/components/headers/Link"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kits/{kitSerial}/configurations":
    get:
      summary: The configurations of the specified kit.
      operationId: listConfigurations
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to retrieve the configurations of.
          schema:
            type: string
      responses:
        '200':
          description: The retrieved configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/KitConfigurationWithPeripherals"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    post:
      summary: Create a new configuration. Either the `source` query parameter
        or the request body must be set (but not both).
      operationId: createConfiguration
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to create a configuration for.
          schema:
            type: string
        - name: source
          in: query
          required: false
          description: The id of the source configuration to clone. If this is
            set, the request body must not be set. The id is allowed to be of a
            configuration of a kit other than specified in `kitSerial`, but the
            agent making the request must have View permission on the kit to
            clone from.
          schema:
            type: number
      requestBody:
        description: The configuration to create. If this is set, the `source`
          query parameter must not be set.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewKitConfiguration"
      responses:
        '201':
          description: The created kit configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitConfiguration"
                type: object
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kit-rpc/{kitSerial}/version":
    get:
      summary: Query the kit for the version it is running.
      operationId: version
      security:
        - bearerAuth: []
      tags:
        - kitRpc
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to query.
          schema:
            type: string
      responses:
        '200':
          description: The version as reported by the kit.
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
        '502':
          $ref: "#/components/responses/ErrorKitRpc"
  "/kit-rpc/{kitSerial}/uptime":
    get:
      summary: Query the kit for its uptime.
      operationId: uptime
      security:
        - bearerAuth: []
      tags:
        - kitRpc
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to query.
          schema:
            type: string
      responses:
        '200':
          description: The uptime in seconds as reported by the kit.
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
        '502':
          $ref: "#/components/responses/ErrorKitRpc"
  "/kit-rpc/{kitSerial}/peripheral-command":
    post:
      summary: Send a command to a peripheral device on the kit.
      operationId: peripheralCommand
      security:
        - bearerAuth: []
      tags:
        - kitRpc
      parameters:
        - name: kitSerial
          in: path
          required: true
          description: The serial of the kit to send a command to.
          schema:
            type: string
      responses:
        '200':
          description: The response of the peripheral device. This can be arbitrary content, such as images. The response's media type is given by the content-type header.
          content:
            '*': {}
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
        '502':
          $ref: "#/components/responses/ErrorKitRpc"
  "/users":
    post:
      summary: Create a user.
      operationId: createUser
      tags:
        - users
      requestBody:
        description: The user to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewUser"
      responses:
        '201':
          description: The user was created.
        '400':
          $ref: "#/components/responses/InvalidParameters"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/users/{username}":
    get:
      summary: Get the user's details.
      operationId: showUserByUsername
      security:
        - bearerAuth: []
      tags:
        - users
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the user to get the details of.
          schema:
            type: string
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    patch:
      summary: Patch the user's details.
      operationId: patchUserByUsername
      security:
        - bearerAuth: []
      tags:
        - users
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the user to patch the details of.
          schema:
            type: string
      requestBody:
        description: The user patch.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchUser"
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/users/{username}/kit-memberships":
    get:
      summary: Get a user's kit memberships.
      operationId: showUserKitMemberships
      security:
        - bearerAuth: []
      tags:
        - users
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the user to get the memberships of.
          schema:
            type: string
      responses:
        '200':
          description: Kit memberships.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/KitMembership"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/me":
    get:
      summary: Your user information.
      operationId: showMe
      security:
        - bearerAuth: []
      tags:
        - access
      responses:
        '200':
          description: Your user information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullUser"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/me/auth":
    post:
      summary: "Authenticate yourself by username and password."
      operationId: authenticateByCredentials
      tags:
        - access
      requestBody:
        description: The login credentials.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthUser"
      responses:
        '200':
          description: The authentication JSON Web Token pair; i.e. a refresh token valid for a year and an access token valid for a much smaller amount of time (generally around 15 minutes). The refresh token should be stored and used to obtain an access token at regular intervals from the /me/refresh endpoint.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationTokens"
        '400':
          $ref: "#/components/responses/InvalidParameters"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/me/refresh":
    post:
      summary: "Obtain an access token from a refresh token."
      operationId: obtainAccessTokenFromRefreshToken
      tags:
        - access
      requestBody:
        description: The refresh token.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthRefreshToken"
      responses:
        '200':
          description: The JSON Web Token necessary for using authenticated endpoints.
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: "#/components/responses/InvalidParameters"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/peripheral-definitions":
    get:
      summary: List all peripheral device definitions.
      operationId: listPeripheralDefinitions
      tags:
        - definitions
      parameters:
        - in: query
          name: after
          schema:
            type: integer
          description: Fetch all peripheral definitions after the given identifier.
        - in: query
          name: withExpectedQuantityTypes
          schema:
            type: boolean
          description: If set to true, include in the output the quantity types the peripheral is expected to produce.
      responses:
        '200':
          description: A paged array of peripheral definitions.
          headers:
            x-next:
              $ref: "#/components/headers/CursorPaging"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeripheralDefinitions"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/quantity-types":
    get:
      summary: List all quantity types.
      operationId: listQuantityTypes
      tags:
        - definitions
      parameters:
        - in: query
          name: after
          schema:
            type: integer
          description: Fetch all quantity types after the given identifier.
      responses:
        '200':
          description: A paged array of quantity types.
          headers:
            x-next:
              $ref: "#/components/headers/CursorPaging"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuantityTypes"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/permissions":
    get:
      summary: List all actions you are permitted to perform on the specified kit.
      operationId: listPermissions
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - in: query
          name: kitSerial
          schema:
            type: string
          description: The serial of the kit to fetch the permissions for.
      responses:
        '200':
          description: An array of actions you are permitted to perform on the specified kit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permissions"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kit-configurations/{configurationId}":
    patch:
      summary: Update the configuration.
      operationId: patchConfiguration
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: configurationId
          in: path
          required: true
          description: The id of the configuration to patch.
          schema:
            type: number
      requestBody:
        description: The configuration patch.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchKitConfiguration"
      responses:
        '200':
          description: The patched kit configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KitConfiguration"
                type: object
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/kit-configurations/{configurationId}/peripherals":
    post:
      summary: Add a peripheral to the configuration.
      operationId: createPeripheral
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: configurationId
          in: path
          required: true
          description: The id of the configuration to add a peripheral to.
          schema:
            type: number
      requestBody:
        description: The peripheral to add.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewPeripheral"
      responses:
        '201':
          description: The added peripheral.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Peripheral"
                type: object
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/peripherals/{peripheralId}":
    patch:
      summary: Update a peripheral.
      operationId: patchPeripheral
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: peripheralId
          in: path
          required: true
          description: The id of the peripheral to update.
          schema:
            type: number
      requestBody:
        description: The peripheral patch.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchPeripheral"
      responses:
        '200':
          description: The peripheral has been deleted.
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
    delete:
      summary: Delete a peripheral.
      operationId: deletePeripheral
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: peripheralId
          in: path
          required: true
          description: The id of the peripheral to delete.
          schema:
            type: number
      responses:
        '200':
          description: The peripheral has been deleted.
        '400':
          $ref: "#/components/responses/InvalidJson"
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/media/{mediaId}":
    delete:
      summary: Delete media.
      operationId: deleteMedia
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: mediaId
          in: path
          required: true
          description: The id of the media to delete.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The media was successfully deleted.
          content:
            "*": {}
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
  "/media/{mediaId}/content":
    get:
      summary: Download media content.
      operationId: getMediaContent
      security:
        - bearerAuth: []
      tags:
        - kits
      parameters:
        - name: mediaId
          in: path
          required: true
          description: The id of the media to download.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The media content.
          content:
            "*": {}
        '401':
          $ref: "#/components/responses/ErrorUnauthorized"
        '429':
          $ref: "#/components/responses/ErrorRateLimit"
        '500':
          $ref: "#/components/responses/ErrorInternalServer"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ProblemDetails:
      type: object
      description: A basic problem report, conforming to RFC7807. Most problems will provide additional fields with information.
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      example:
        type:
          about:blank
        title: Bad Request
        status: 400
    ProblemInternalServer:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
        - example:
            type: "about:blank"
            title: "Internal Server Error"
            status: 500
    ProblemRateLimit:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
        - type: object
          required:
            - waitTimeMillis
          properties:
            waitTimeMillis:
              type: number
          example:
            type: "/probs/rate-limit"
            waitTimeMillis: 250
            title: "Your request has been rate limited."
            status: 429
    ProblemInvalidParameters:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
        - type: object
          properties:
            invalidParameters:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/InvalidParameter"
      example:
        type: "/probs/invalid-parameters"
        title: Your request parameters did not validate.
        status: 400
        invalidParameters:
          username:
            - mustBeUnique
          emailAddress:
            - mustBeEmailAddress
            - mustHaveLengthBetween:
                min: 0
                max: 255
    InvalidParameter:
      type: array
      items:
        anyOf:
          - type: string
            enum:
              - mustBeEmailAddress
              - mustBeUrl
              - alreadyExists
              - other
          - type: object
            required:
              - mustBeInRange
            properties:
              mustBeInRange:
                type: object
                required:
                  - min
                  - max
                properties:
                  min:
                    type: number
                    format: float
                  max:
                    type: number
                    format: float
          - type: object
            required:
              - mustHaveLengthBetween
            properties:
              mustHaveLengthBetween:
                type: object
                anyOf:
                  - required:
                      - min
                  - required:
                      - max
                properties:
                  min:
                    type: integer
                  max:
                    type: integer
          - type: object
            required:
              - mustHaveLengthExactly
            properties:
              mustHaveLengthExactly:
                type: object
                required:
                  - length
                properties:
                  length:
                    type: integer
          - type: object
            required:
              - invalidToken
            properties:
              invalidToken:
                type: object
                required:
                  - category
                properties:
                  category:
                    type: string
                    enum:
                      - missing
                      - malformed
                      - expired
    ProblemKitRpc:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
        - example:
            type: "/probs/kit-rpc"
            title: "There was an issue with the kit RPC response"
            status: 502
    Kit:
      type: object
      required:
        - id
        - serial
        - name
      properties:
        id:
          type: integer
          format: int32
        serial:
          type: string
        name:
          type: string
        description:
          type: string
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
        privacyPublicDashboard:
          type: boolean
        privacyShowOnMap:
          type: boolean
        lastSeen:
          type: string
          format: "date-time"
    PatchKit:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
        privacyPublicDashboard:
          type: boolean
        privacyShowOnMap:
          type: boolean
    NewKit:
      type: object
      required:
            - privacyPublicDashboard
            - privacyShowOnMap
      properties:
            name:
              type: string
            description:
              type: string
            latitude:
              type: number
              format: float
            longitude:
              type: number
              format: float
            privacyPublicDashboard:
              type: boolean
            privacyShowOnMap:
              type: boolean
      example:
            latitude: 52.1326
            longitude: 5.2913
            privacyShowOnMap: true
            privacyPublicDashboard: false
    Kits:
      type: array
      items:
        $ref: "#/components/schemas/Kit"
    KitMembership:
      type: object
      required:
        - id
        - user
        - kit
        - accessConfigure
        - accessSuper
        - datetimeLinked
      properties:
        id:
          type: integer
          format: int32
        user:
          $ref: "#/components/schemas/User"
        kit:
          $ref: "#/components/schemas/Kit"
        accessConfigure:
          type: boolean
        accessSuper:
          type: boolean
        datetimeLinked:
          type: string
          format: "date-time"
    NewKitMembership:
      type: object
      required:
        - username
        - accessConfigure
        - accessSuper
      properties:
        username:
          type: string
        accessConfigure:
          type: boolean
        accessSuper:
          type: boolean
    PatchKitMembership:
      type: object
      properties:
        accessConfigure:
          type: boolean
        accessSuper:
          type: boolean
    NewUser:
      type: object
      required:
        - username
        - password
        - emailAddress
      properties:
        username:
          type: string
        password:
          type: string
        emailAddress:
          type: string
          format: email
      example:
        username: douglas
        password: hunter2
        emailAddress: d.adams@example.com
    PatchUser:
      type: object
      properties:
        displayName:
          type: string
        emailAddress:
          type: string
        useEmailAddressForGravatar:
          type: boolean
    AuthUser:
      type: object
      required:
            - username
            - password
      properties:
            username:
              type: string
            password:
              type: string
      example:
            username: douglas
            password: hunter2
    FullUser:
      type: object
      required:
        - id
        - username
        - displayName
        - emailAddress
        - useEmailAddressForGravatar
        - gravatarAlternative
      properties:
        id:
          type: integer
          format: int32
        username:
          type: string
        displayName:
          type: string
        emailAddress:
          type: string
          format: email
        useEmailAddressForGravatar:
          type: boolean
        gravatarAlternative:
          type: string
      example:
        id: 42
        username: douglas
        displayName: Douglas Adams
        emailAddress: d.adams@example.com
        useEmailAddressForGravatar: false
        gravatarAlternative: "3NbpHjTp4fYyxnPw4$6xcTp!J%hyhdJq"
    User:
      type: object
      required:
        - username
        - displayName
        - gravatar
      properties:
        username:
          type: string
        displayName:
          type: string
        gravatar:
          type: string
      example:
        username: douglas
        displayName: Douglas Adams
        gravatar: "3NbpHjTp4fYyxnPw4$6xcTp!J%hyhdJq"
    AuthRefreshToken:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string
    AuthenticationTokens:
      type: object
      required:
        - refreshToken
        - accessToken
      properties:
        refreshToken:
          type: string
        accessToken:
          type: string
    PeripheralDefinition:
      type: object
      required:
        - id
        - name
        - symbolLocation
        - symbol
        - configurationSchema
        - commandSchema
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        description:
          type: string
        brand:
          type: string
        model:
          type: string
        symbolLocation:
          type: string
        symbol:
          type: string
        configurationSchema:
          description: "A JSON schema specifying valid configuration documents."
        commandSchema:
          description: "A JSON schema specifying valid command documents."
          nullable: true
        expectedQuantityTypes:
          type: array
          items:
            type: integer
            format: int32
    PeripheralDefinitions:
      type: array
      items:
        $ref: "#/components/schemas/PeripheralDefinition"
    ExpectedQuantityType:
      type: object
      required:
        - id
        - peripheralDefinition
        - quantityType
      properties:
        id:
          type: integer
          format: int32
        peripheralDefinition:
          type: integer
          format: int32
        quantityType:
          type: integer
          format: int32
    Peripheral:
      type: object
      required:
        - id
        - kitId
        - kitConfigurationId
        - peripheralDefinitionId
        - name
        - configuration
      properties:
        id:
          type: integer
          format: int32
        kitId:
          type: integer
          format: int32
        kitConfigurationId:
          type: integer
          format: int32
        peripheralDefinitionId:
          type: integer
          format: int32
        name:
          type: string
        configuration:
          description: "A configuration document."
    NewPeripheral:
      type: object
      required:
        - peripheralDefinitionId
        - name
        - configuration
      properties:
        peripheralDefinitionId:
          type: integer
          format: int32
        name:
          type: string
        configuration:
          description: "A configuration document. Should conform to the JSON schema specified by the corresponding peripheral definition."
    PatchPeripheral:
      type: object
      properties:
        name:
          type: string
        configuration:
          description: "A configuration document. Should conform to the JSON schema specified by the corresponding peripheral definition."
    Peripherals:
      type: array
      items:
        $ref: "#/components/schemas/Peripheral"
    QuantityType:
      type: object
      required:
        - id
        - physicalQuantity
        - physicalUnit
      properties:
        id:
          type: integer
          format: int32
        physicalQuantity:
          type: string
        physicalUnit:
          type: string
        physicalUnitSymbol:
          type: string
    QuantityTypes:
      type: array
      items:
        $ref: "#/components/schemas/QuantityType"
    Permission:
      type: string
      enum:
        - view
        - subscribeRealTimeMeasurements
        - editDetails
        - editConfiguration
        - editMembers
        - setSuperMember
    Permissions:
      type: array
      items:
        $ref: "#/components/schemas/Permission"
    KitConfiguration:
      type: object
      required:
        - id
        - kitId
        - controllerSymbolLocation
        - controllerSymbol
        - controlRules
        - active
        - neverUsed
      properties:
        id:
          type: integer
          format: int32
        kitId:
          type: integer
          format: int32
        description:
          type: string
        controllerSymbolLocation:
          type: string
        controllerSymbol:
          type: string
        controlRules:
          description: "A kit control document."
        active:
          type: boolean
        neverUsed:
          type: boolean
    NewKitConfiguration:
      type: object
      properties:
        description:
          type: string
    PatchKitConfiguration:
      type: object
      properties:
        description:
          type: string
        controllerSymbolLocation:
          type: string
        controllerSymbol:
          type: string
        controlRules:
          description: "A kit control document. The valid values are currently not specified here."
        active:
          type: boolean
    KitConfigurationWithPeripherals:
      allOf:
        - $ref: "#/components/schemas/KitConfiguration"
        - type: object
          required:
            - peripherals
          properties:
            peripherals:
              $ref: "#/components/schemas/Peripherals"
    AggregateMeasurement:
      type: object
      required:
        - id
        - peripheralId
        - kitId
        - kitConfigurationId
        - quantityTypeId
        - datetimeStart
        - datetimeEnd
        - values
      properties:
        id:
          type: string
          format: uuid
        peripheralId:
          type: number
          format: int32
        kitId:
          type: number
          format: int32
        kitConfigurationId:
          type: number
          format: int32
        quantityTypeId:
          type: number
          format: int32
        datetimeStart:
          type: string
          format: date-time
        datetimeEnd:
          type: string
          format: date-time
        values:
          type: object
          additionalProperties:
            type: number
    Media:
      type: object
      required:
        - id
        - peripheralId
        - kitId
        - kitConfigurationId
        - datetime
        - name
        - type
        - metadata
        - size
      properties:
        id:
          type: string
          format: uuid
        peripheralId:
          type: number
          format: int32
        kitId:
          type: number
          format: int32
        kitConfigurationId:
          type: number
          format: int32
        datetime:
          type: string
          format: date-time
        name:
          type: string
        type:
          type: string
        metadata: {}
        size:
          type: number
          format: int64
  headers:
    CursorPaging:
      description: A link to the next page.
      required: false
      schema:
        type: string
    Link:
      description: Contains related links, for example to link to a next page if a next page exists. See [RFC 8288](https://tools.ietf.org/html/rfc8288). The URIs in these links are intended to be followed directly by the client using GET requests with the same authentication headers as the original request. The client does not need to understand the form of the URIs.
      schema:
        type: string
        example: </kits/k-wbn3-rr46-twf8/aggregate-measurements?cursor=%5B%222020-06-03T20%3A14%3A56.688Z%22%2C%2266be0e90-6b62-46a6-b681-0947df0bafcc%22%5D>; rel="next"
  responses:
    InvalidJson:
      description: The JSON you provided was invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    InvalidParameters:
      description: You provided invalid parameters.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemInvalidParameters"
    ErrorUnauthorized:
      description: The request was denied because you are not authorized to access the resource.
    ErrorRateLimit:
      description: The request was denied because you exceeded the rate limit.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemRateLimit"
    ErrorInternalServer:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemInternalServer"
    ErrorKitRpc:
      description: "An error occurred proxying the RPC request: either the connection could not be made, or the kit reported an error."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemKitRpc"