openapi.yaml

openapi: 3.0.1
info:
  title: Mage API
  description: Mage API
  contact:
    name: Mage Support
    email: mage@nga.mil
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 6.0.1
servers: []
security:
  - mageToken: []
tags:
  - name: Auth
  - name: Authentication & Authorization
  - name: Authentication Configuration
    description: Authentication configurations define the strategies used to authenticate users into the system.
  - name: Device
  - name: Event
  - name: Export
  - name: Feed
    description: >
      Feeds are supplemental data sets that participants can add to their active event context.
      Feed content could have any combination of spatial, temporal, or informational dimensions.
  - name: Icon
  - name: Layer
  - name: Location
  - name: Observation
  - name: Role
  - name: Settings
  - name: Team
  - name: User
paths:
  /api/logins:
    get:
      tags: [ Auth ]
      description: >
        Return an array of user login events.  This operation requires
        `READ_USER` permission.
      operationId: getUserLogins
      parameters:
        - name: userId
          in: query
          description: Return only logins for the given `userId`
          schema: { $ref: '#/components/schemas/User/properties/id' }
        - name: deviceId
          in: query
          description: Return only logins from the given `deviceId`
          schema: { $ref: '#/components/schemas/Device/properties/id' }
        - name: startDate
          in: query
          description: ISO 8601 start date to filter (inclusive)
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: ISO 8601 end date filter (exclusive)
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: >
            Limit the number of results to the given value.  The default value
            is `10`.
          schema:
            type: integer
        - name: firstLoginId
          in: query
          description: The ID of the first login in the range of results
          schema: { $ref: '#/components/schemas/Login/properties/id' }
        - name: lastLoginId
          in: query
          description: The ID of the last login in the range of results
          schema: { $ref: '#/components/schemas/Login/properties/id' }
      responses:
        200:
          description: >
            Success - return the array of login events according to the given
            query parameters.
          content:
            application/json:
              schema:
                type: object
                required: [ logins ]
                properties:
                  next:
                    type: string
                    format: uri
                    description: Link to the next chunk of results
                  prev:
                    type: string
                    format: uri
                    description: Link to the previous chunk of results
                  logins:
                    type: array
                    items: { $ref: '#/components/schemas/Login' }

  /api/logout:
    post:
      tags:
      - Auth
      description: Invaldate the auth token for the requesting user.
      operationId: logout
      responses:
        200:
          description: logout response

  /auth/{authenticationStrategy}/signin:
    post:
      tags: [ Authentication & Authorization ]
      summary: Authentication
      description: Authenticate a user using a given strategy.
      operationId: authenticate
      security:
        []
      parameters:
        - name: authenticationStrategy
          in: path
          description: Authentication strategy.
          required: true
          schema:
            type: string
            enum: [ local, ldap, saml, oauth, openidconnect ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserIn' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/UserIn' }
      responses:
        200:
          description: Successfully signed in.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Authentication' }

  /auth/token:
    post:
      tags: [ Authentication & Authorization  ]
      summary: Device Authorization
      description: Authorize a device.  If device does not exist, it may also be created via this method.
      operationId: authorize
      security:
        - authenticationToken: []
      parameters:
        - name: uid
          in: query
          description: Id of the device that requires provisioning
          required: true
          schema: { $ref: '#/components/schemas/Device/properties/id' }
        - name: name
          in: query
          description: Name of the device
          schema: { $ref: '#/components/schemas/Device/properties/name' }
        - name: description
          in: query
          description: Description of the device
          schema: { $ref: '#/components/schemas/Device/properties/description' }
        - name: appVersion
          in: query
          description: Application version of the device (required if creating a new device)
          schema: { $ref: '#/components/schemas/Device/properties/appVersion' }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DeviceIn' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/DeviceIn' }
      responses:
        200:
          description: Successful device authorization, Mage api token is returned.
        401:
          description:  User is not authorized.  Typically this means you need to authenticate `/auth/local/signin`.
        403:
          description: Failure to provision the device.  This typically means the device needs to be registered.

  /api/authentication/configuration/:
    get:
      tags: [Authentication Configuration]
      summary: Get an array of all authentication configurations
      description: Get all authentication configurations.  The client must have `READ_AUTH_CONFIG` permission.
      operationId: getAllAuthConfigs
      parameters:
        - { $ref: '#/components/parameters/authenticationConfigurationIncludeDisabled' }
      responses:
        200:
          description: A list of all authentication configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthenticationConfiguration'
        401:
          description: User is not authorized to view authentication configurations.
    post:
      tags: [Authentication Configuration]
      summary: Create a new authentication configuration
      description: Create a new authentication configuration.  If enabled, it will allow users to use this method.
                   The client must have `UPDATE_AUTH_CONFIG` permission.
      operationId: createNewAuthConfig
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AuthenticationConfiguration' }
      responses:
        200:
          description: The created authentication configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationConfiguration'
        401:
          description: User is not authorized to create authentication configurations.
  /api/authentication/configuration/{id}:
    parameters:
      - { $ref: '#/components/parameters/authenticationConfigurationIdInPath' }
    put:
      tags: [ Authentication Configuration ]
      summary: Update an authentication configuration
      description: >
        Update the authentication configuration.
        The client must have `UPDATE_AUTH_CONFIG` permission.
      operationId: updateAuthConfigById
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AuthenticationConfiguration' }
      responses:
        200:
          description: authentication configuration update response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationConfiguration'
    delete:
      tags: [ Authentication Configuration ]
      summary: Delete  an authentication configuration
      description: >
        Delete the authentiction configuration document by `id`.
        The client must have `UPDATE_AUTH_CONFIG` permission.
      operationId: deleteAutheConfig
      responses:
        204:
          description: Success - authentication configuration
  /api/authentication/configuration/count/{id}:
    parameters:
      - { $ref: '#/components/parameters/authenticationConfigurationIdInPath' }
    get:
      tags: [ Authentication Configuration ]
      summary: Count the number of users for a given configuration
      description: >
        Count the number of users for a given configuration.
        The client must have `READ_AUTH_CONFIG` permission.
      operationId: countUsersByAuthConfig
      responses:
        200:
          description: The number of users created from the provided authentication.

  /api/users:
    post:
      tags: [ User ]
      description: >
        Create a new user.  Duplicate usernames are not allowed.
        If the requesting user is an admin, i.e., has the `CREATE_USER`
        permission, the user record will be active.  Otherwise, the user will
        be inactive and an admin must activate the user later.  Additionally,
        the `roleId` key is required when the requesting user is an admin.
        Otherwise, the created user receives a default role.  When the request
        body contains `multipart/form-data`, Mage will handle the `icon` and/or
        `avatar` file form parameters.  The server only sets the user's map
        icon if the requesting user has the `CREATE_USER` permission.
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserCreate' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/UserCreate' }
      responses:
        200:
          description: The created user document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    get:
      deprecated: true
      tags: [ User ]
      description: >
        This operation is deprecated and now only returns an empty response.  The client must have `READ_USER` permission.
      summary: Get an array of users.
      operationId: getUsers
      parameters:
        - in: query
          name: active
          description: Return only active or inactive users.
          schema:
            type: boolean
        - in: query
          name: enabled
          description: Return only enabled or disabled users.
          schema:
            type: boolean
        - in: query
          name: start
          description: Used with pagination.  Indicates the record number to start (leave blank for initial set of results).
          schema:
            type: integer
        - in: query
          name: limit
          description: Used with pagination.  Maximum number of records to return.
          schema:
            type: integer
        - in: query
          name: sort
          description: Describes the sort order.  Values allowed are asc, desc, ascending, descending, 1, and -1.
          content:
            application/json:
              schema:
                type: object
                required:
                  - displayName
                  - _id
                properties:
                  displayName:
                    type: string
                  _id:
                    type: string
        - in: query
          name: populate
          description: >
            Pre-populate the given relation keys in the result user documents.
            Currently, this only supports 'roleId'.
          schema: { $ref: '#/components/schemas/CommaSeparatedTokens' }
      responses:
        200:
          description: An array of user documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /api/users/count:
    get:
      tags: [ User ]
      description: >
        Return the number of users in the database.  The client must
        have `READ_USER` permission.
      summary: Count the number of users in the database.
      operationId: getUserCount
      parameters:
        - in: query
          name: active
          schema:
            type: boolean
        - in: query
          name: enabled
          schema:
            type: boolean
      responses:
        200:
          description: A successful request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Count' }
  /api/next-users/search:
    get:
      tags: [ User ]
      description: Search for users. The client must have `READ_USER` permission.
      summary: User search.
      operationId: userSearch
      parameters:
        - in: query
          name: term
          schema:
            type: string
        - in: query
          name: page_size
          schema:
            type: integer
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: total
          schema:
            type: boolean
      responses:
        200:
          description: Users matching the search
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PageOfUsers' }
  /api/users/myself:
    get:
      tags: [ User ]
      description: >
        Return the user document for the requesting user based on the
        provided authentication token.
      operationId: getMyself
      responses:
        200:
          description: The user document for the requesting user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags: [ User ]
      description: >
        Update the user document for the requesting user based on the
        provided authentication token.  This operation does not support
        changing the requesting user's password; use
        `PUT /api/users/myself/password` for that.
      operationId: updateMyself
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserUpdateSelf' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/UserUpdateSelf' }
      responses:
        200:
          description: The updated user document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /api/users/myself/password:
    put:
      tags: [ User ]
      description: Update the password for the requesting user.
      operationId: updateMyPassword
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newPassword:
                  type: string
                  format: password
                newPasswordConfirm:
                  type: string
                  format: password
      responses:
        200:
          description: Successful password update; return the user document
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
  /api/users/myself/status:
    put:
      tags: [ User ]
      description: Update the status of the requesting user.
      operationId: updateMyStatus
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
              required: [ status ]
      responses:
        200:
          description: Successful status update
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
    delete:
      tags: [ User ]
      description: Delete the status of the requesting user.
      operationId: deleteMyStatus
      responses:
        200:
          description: Successfully deleted status
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
  /api/users/{userId}:
    parameters:
      - { $ref: '#/components/parameters/userIdInPath' }
    get:
      tags:
      - User
      description: >
        Return the user document whose `id` equals the `userId` path parameter.
        The client must have `READ_USER` permission.
      operationId: getUserById
      responses:
        200:
          description: The updated user document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags: [ User ]
      description: >
        Update the user document whose `id` equals the `userId` path parameter.
        The client must have `UPDATE_USER` permission.
      operationId: updateUserById
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserIn' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/UserIn' }
      responses:
        200:
          description: user update response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      tags: [ User ]
      description: >
        Delete the user document whose `id` equals the `userId` path parameter.
        The client must have `DELETE_USER` permission.
      operationId: deleteUser
      responses:
        204:
          description: Success - user deleted
  /api/users/{userId}/avatar:
    parameters:
      - { $ref: '#/components/parameters/userIdInPath' }
    get:
      tags: [ User ]
      description: Returns users avatar based on user id
      operationId: getUserAvatar
      responses:
        200:
          description: user avatar response
          content:
            image/*:
              schema:
                type: string
                format: binary
  /api/users/{userId}/icon:
    parameters:
      - { $ref: '#/components/parameters/userIdInPath' }
    get:
      tags: [ User ]
      description: Returns users map icon based on user id
      operationId: getUserIcon
      responses:
        200:
          description: user icon response
          content:
            image/*:
              schema:
                type: string
                format: binary
  /api/users/{userId}/events/{eventId}/recent:
    parameters:
      - { $ref: '#/components/parameters/userIdInPath' }
      - { $ref: '#/components/parameters/eventIdInPath' }
    post:
      tags: [ User ]
      description: >
        Add the given event to top of recent list for the given user.  The list
        is capped at 5.
      operationId: addRecentEventForUser
      responses:
        200:
          description: user response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /api/devices:
    post:
      tags:
        - Device
      summary: Create a device
      description: >
        Save a new device document in the database.  The request client must
        have `CREATE_DEVICE` permission. `DEPRECATED`: Clients should be creating devices via authorize `/auth/{strategy}/authorize`
      operationId: createDevice
      requestBody:
        $ref: '#/components/requestBodies/DeviceIn'
      deprecated:
        true
      responses:
        200:
          description: new device response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
    get:
      tags:
        - Device
      description: >
        Return an array of all the device documents in the database.  The
        requesting client must have `READ_DEVICE` permission.
      summary: Get all the device documents in the database.
      operationId: getDevices
      parameters:
        - in: query
          name: registered
          description: Return only registered or unregistered devices.
          schema: { $ref: '#/components/schemas/Device/properties/registered' }
        - in: query
          name: start
          description: Used with pagination.  Indicates the record number to start (leave blank for initial set of results).
          schema:
            type: integer
        - in: query
          name: limit
          description: Used with pagination.  Maximum number of records to return.
          schema:
            type: integer
        - in: query
          name: sort
          description: Describes the sort order.  Values allowed are asc, desc, ascending, descending, 1, and -1.
          content:
            application/json:
              schema:
                type: object
                required:
                  - userAgent
                  - _id
                properties:
                  userAgent:
                    type: string
                  _id:
                    type: string
        - in: query
          name: expand
          description: >
            Comma-separated list of relation keys to populate with related
            documents.  Currently the API only supports the `user` key.
          schema: { $ref: '#/components/schemas/CommaSeparatedTokens' }
      responses:
        200:
          description: Success - an array of device documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
  /api/devices/count:
    get:
      tags:
        - Device
      operationId: getDeviceCount
      description: Return the number of devices in the database.
      summary: Count the number of devices in the database.
      parameters:
        - in: query
          name: registered
          schema:
            type: boolean
      responses:
        200:
          description: Success - return the device count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
  /api/devices/{deviceId}:
    parameters:
      - $ref: '#/components/parameters/deviceIdInPath'
    get:
      tags:
        - Device
      description: >
        Return the device document whose ID matches the path parameter for the
        device ID.  The requesting client must have READ_DEVICE permission.
      operationId: getDeviceById
      responses:
        200:
          description: device response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
    put:
      tags:
        - Device
      description: >
        Update a device document whose ID matches the path parameter for the
        device ID.  The requesting client must have `UPDATE_DEVICE` permission.
      operationId: updateDeviceById
      requestBody:
        $ref: '#/components/requestBodies/DeviceIn'
      responses:
        200:
          description: device update response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
    delete:
      tags:
        - Device
      description: >
        Delete a device document whose ID matches the path parameter for the
        device ID.  The requesting client must have `DELETE_DEVICE` permission.
      operationId: deleteDeviceByIds
      responses:
        204:
          description: user deleted

  /api/teams:
    post:
      tags: [ Team ]
      description: >
        Save a new team document to the database.  The requesting user must
        have `CREATE_TEAM` permission.
      operationId: createTeam
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TeamCreate' }
          application/x-www-form-urlencoded:
            schema: { $ref: '#/components/schemas/TeamCreate' }
      responses:
        200:
          description: Success - the created team document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    get:
      tags: [ Team ]
      description: >
        Return all the teams.  The requesting client must have `READ_TEAM`
        permission.
      operationId: getTeams
      parameters:
        - in: query
          name: start
          description: Used with pagination.  Indicates the record number to start (leave blank for initial set of results).
          schema:
            type: integer
        - in: query
          name: limit
          description: Used with pagination.  Maximum number of records to return.
          schema:
            type: integer
        - in: query
          name: sort
          description: Describes the sort order.  Values allowed are asc, desc, ascending, descending, 1, and -1.
          content:
            application/json:
              schema:
                type: object
                required:
                  - name
                  - _id
                properties:
                  name:
                    type: string
                  _id:
                    type: string
        - in: query
          name: omit_event_teams
          description: >
            Whether to omit the event's implicit team that Mage automatically
            creates for adding individual users to an event.
          schema:
            type: boolean
        - in: query
          name: with_members
          description: >
            Return only teams that have the given user IDs as members.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User/properties/id'
        - in: query
          name: without_members
          description: >
            Return only teams that do not have the given user IDs as members.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User/properties/id'
        - in: query
          name: term
          description: >
            Return teams whose name or description field contains the given search term.
          schema:
            type: string
      responses:
        200:
          description: Success - an array of team documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Team'
  /api/teams/count:
    get:
      tags: [ Team ]
      description: >
        Get the number of teams in the database.  The requesting user must have
        have `READ_TEAM` permission.
      operationId: getTeamCount
      responses:
        200:
          description: Success - return the number of teams
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Count' }
  /api/teams/{teamId}:
    parameters:
      - $ref: '#/components/parameters/teamIdInPath'
    get:
      tags: [ Team ]
      description: >
        Return the team document whose ID matches the team ID path parameter.
        The requesting client must have `READ_TEAM` permission.
      operationId: getTeamById
      responses:
        200:
          description: Success - a team document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    put:
      tags: [ Team ]
      description: >
        Update the team document whose ID matches the team ID in the path.
        The requesting user must have `UPDATE_TEAM` permission.
      operationId: updateTeamById
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TeamIn' }
          application/x-www-form-urlencoded:
            schema: { $ref: '#/components/schemas/TeamIn' }
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    delete:
      tags: [ Team ]
      description: >
        Delete the team document whose ID matches the team ID in the path.  The
        request user must have `DELETE_TEAM` permission.
      operationId: deleteTeam
      responses:
        204:
          description: Success - team deleted
  /api/teams/{teamId}/users:
    parameters:
      - { $ref: '#/components/parameters/teamIdInPath' }
    post:
      tags: [ Team ]
      operationId: addUserToTeam
      description: >
        Add a user to a team.  The request user must have `UPDATE_TEAM`
        permission as well as an ACL entry in the team document with `update`
        permission.
      requestBody:
        description: The user ID reference to add to the target team
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRef'
        required: true
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Team' }
  /api/teams/{teamId}/users/{userId}:
    parameters:
      - { $ref: '#/components/parameters/teamIdInPath' }
      - { $ref: '#/components/parameters/userIdInPath' }
    delete:
      tags: [ Team ]
      operationId: removeUserFromTeam
      description: >
        Remove a user from a team.  The requesting user must have `UPDATE_TEAM`
        permission as well as an ACL entry in the team document with `update`
        permission.
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Team' }
  /api/teams/{teamId}/acl/{userId}:
    parameters:
      - { $ref: '#/components/parameters/teamIdInPath' }
      - { $ref: '#/components/parameters/userIdInPath' }
    put:
      tags: [ Team ]
      operationId: setUserAccessForTeam
      description: >
        Update a team ACL entry.  The requesting user must have `UPDATE_TEAM`
        permission, as well as an ACL entry in the team document with `update`
        permission.
      requestBody:
        $ref: '#/components/requestBodies/ACLRoleUpdate'
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Team' }
    delete:
      tags: [ Team ]
      operationId: removeUserAccessFromTeam
      description: >
        Delete a team ACL entry.  The requesting user must have `UPDATE_TEAM`
        permission, as well as an ACL entry in the team document with `update`
        permission.
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Team' }

  /api/events:
    post:
      tags: [ Event ]
      operationId: createEvent
      description: >
        Create a new event.  The requesting user must have `CREATE_EVENT`
        permission.  Mage assigns the requesting user to the event's ACL with
        the `OWNER` role.  Creating a new event implicitly creates a team
        coupled to the event by the team's `teamEventId` property.  One can
        add users to this team to allow access to the event on an individual
        basis.  This allows team and user access management to remain
        consistent across the API without having to maintain a list of users
        separately for each event.
      requestBody:
        description: The new event document
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventCreate'
        required: true
      responses:
        201:
          description: Success - return the created event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    get:
      tags: [ Event ]
      description: >
        Get all of the Mage server's events.  The requesting user must have
        `READ_EVENT_ALL` permission and an ACL entry on the even with `read`
        permission.
      operationId: getEvents
      parameters:
        - in: query
          name: projection
          schema:
            type: string
        - in: query
          name: state
          schema:
            type: string
            enum: [ active, complete ]
        - in: query
          name: userId
          schema:
            $ref: '#/components/schemas/User/properties/id'
          description: >
            Return only events the given user can access.
        - in: query
          name: populate
          schema:
            type: boolean
          description: >
            When omitted or not `false`, populate the teams and layers related
            to each event.  Otherwise, the event documents will only contain
            the IDs of the related teams and layers.  When populated, the
            event documents will contain the `teams` and `layers` keys mapped to
            arrays of their respective documents.  When not populated, the
            event documents will contain the `eventIds` and `layerIds` keys
            mapped to arrays of ID strings.  Populated team documents will NOT
            contain populated user documents.
      responses:
        200:
          description: Success - return an array of event documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
  /api/events/count:
    get:
      tags: [ Event ]
      description: >
        Get the number of events in the database.  The requesting user must
        have `READ_EVENT_ALL` permission.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
  /api/events/{eventId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Event ]
      description: >
        Return the event with the ID specified in the path.  The requesting
        user must have `READ_EVENT_ALL` permission and an ACL entry with `read`
        permission on the even.
      operationId: getEventById
      parameters:
        - in: query
          name: populate
          schema:
            type: boolean
          description: >
            When omitted or not `false`, populate the teams and layers related
            to each event.  Otherwise, the event documents will only contain
            the IDs of the related teams and layers.  When populated, the
            event documents will contain the `teams` and `layers` keys mapped to
            with arrays of their respective documents.  When not populated, the
            event documents will contain the `eventIds` and `layerIds` keys
            mapped to arrays of ID strings.  Populated team documents will NOT
            contain populated user documents.
        - in: query
          name: projection
          schema:
            type: string
      responses:
        200:
          description: Sucess - return the event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    put:
      tags: [ Event ]
      description: >
        Update the event with the ID specified in the path.  The requesting
        user must have `UPDATE_EVENT` permission and an ACL entry on the event
        with `update` permission.
      operationId: updateEventById
      requestBody:
        description: event update body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventUpdate'
        required: true
      responses:
        200:
          description: Success - return the update event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    delete:
      tags: [ Event ]
      description: >
        Delete the event with the ID specified in the path.  The requesting
        user must have `DELETE_EVENT` permission and an ACL entry on the event
        with `delete` permission.
      operationId: deleteEvent
      responses:
        204:
          description: Success - event deleted
  /api/events/{eventId}/forms:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    post:
      tags: [ Event ]
      description: >
        Add a form to the specified event.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      operationId: addFormToEvent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FormImport'
      responses:
        201:
          description: Success - return the updated event document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/events/{eventId}/forms/{formId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
    put:
      tags: [ Event ]
      operationId: updateFormById
      description: >
        Update the specified form for the specified event.  The requesting
        client must have `UPDATE_EVENT` permission and an ACL entry on the
        event with `update` permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Form'
      responses:
        200:
          description: Success - return the updated form document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
  /api/events/{eventId}/{formId}/form.zip:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
    get:
      tags: [ Event ]
      operationId: exportForm
      description: >
        Export a zip archive of the form.  The zip file includes metadata and
        map symbology icons in the following layout.
        ```
        form/form.json # the form document
        icons/ # a directory that contains the form's icon image files
        icons/icon.png
        # icon for 'primary_1' primary value with no variant value
        icons/<primary_1>/icon.png
        # icon for 'primary_1' primary value with 'variant_1' variant value
        icons/<primary_1>/<variant_1>/icon.png
        # icon for 'primary_1' primary value with 'variant_2' variant value
        icons/<primary_1>/<variant_2>/icon.png
        ...
        # and so on for any combination of primary and variant field values
        # that one wishes to have a specific map icon
        icons/<primary_n>/<variant_n>/icon.png
        ```
        The `<primary_x>` and `<variant_x>` directory components above are
        named after the choice values of the form's primary and variant
        select fields, respectively.  Each `primary_x/variant_x` directory
        contains the map icon image that Mage clients will use to represent
        observations with those values on a map.  Mage clients will use the
        form's default icon image to represent primary/variant combinations
        that are not present in the `icons` directory.  The requesting user
        must have `READ_EVENT_ALL` permission and an ACL entry with `read`
        permission on the event.
      responses:
        200:
          description: >
            Success - return a zip file of the form meta-data and icons.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/events/{eventId}/form/icons.zip:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Event ]
      operationId: getEventIcons
      description: >
        Get a zip file containing all the map icons for the forms of an event.
        The requesting user must have `READ_EVENT_ALL` permission and an ACL
        entry with `read` permission on the event.  The top level of the zip
        file will contain one directory entry, `icons/`, which contains the
        icon files under directories named according to primary and variant
        field values as described above in the `exportForm` operation.
      responses:
        200:
          description: Success - return a zip file of icon images for the event.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/events/{eventId}/icons/{formId}.json:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
    get:
      tags: [ Event ]
      operationId: getFormIcons
      description: >
        Return all the icons for the specified form as base-64 strings in a
        JSON document.  The requesting user must have `READ_EVENT_ALL`
        permission and an ACL entry with `read` permission on the event.
      responses:
        200:
          description: Success - return the array of form icons.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormIconEmbedded'
  /api/events/{eventId}/icons:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    post:
      tags: [ Event ]
      operationId: uploadEventIcon
      description: >
        Upload the default icon for the specified event.  The requesting user
        must have `UPDATE_EVENT` permission and an ACL entry on the event with
        `update` permission.
      requestBody:
        $ref: '#/components/requestBodies/FormIconUpload'
      responses:
        200:
          $ref: '#/components/responses/FormIconInfo'
    get:
      tags: [ Event ]
      operationId: getEventIcon
      description: >
        Get the default icon image for the specified event.  The requesting user
        must have `READ_EVENT_ALL` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          $ref: '#/components/responses/FormIconContent'
    delete:
      tags: [ Event ]
      operationId: deleteEventIcon
      description: >
        Delete the default icon from the specified event.  The requesting user
        must have `UPDATE_EVENT` permission and an ACL entry on the event with
        `update` permission.
      responses:
        204:
          description: Success - icon deleted.
  /api/events/{eventId}/icons/{formId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
    post:
      tags: [ Event ]
      operationId: uploadDefaultFormIcon
      description: >
        Upload the default icon for the specified form.  The requesting user
        must have 'UPDATE_EVENT' permission and an ACL entry on the event with
        `update` permission.
      requestBody:
        $ref: '#/components/requestBodies/FormIconUpload'
      responses:
        200:
          $ref: '#/components/responses/FormIconInfo'
    get:
      tags: [ Event ]
      operationId: getDefaultFormIcon
      description: >
        Get the default icon for the specified form.  The requesting user must
        have `READ_EVENT_ALL` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          $ref: '#/components/responses/FormIconContent'
    delete:
      tags: [ Event ]
      operationId: deleteDefaultFormIcon
      description: >
        Delete the default icon from the form.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      responses:
        204:
          description: Success - icon deleted.
  /api/events/{eventId}/icons/{formId}/{primary}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
      - $ref: '#/components/parameters/primaryFieldValueInPath'
    post:
      tags: [ Event ]
      operationId: uploadPrimaryFormIcon
      requestBody:
        $ref: '#/components/requestBodies/FormIconUpload'
      responses:
        200:
          $ref: '#/components/responses/FormIconInfo'
    get:
      tags: [ Event ]
      operationId: getPrimaryFormIcon
      description: >
        Get the default icon for the specified form.  The requesting user must
        have `READ_EVENT_ALL` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          $ref: '#/components/responses/FormIconContent'
    delete:
      tags: [ Event ]
      operationId: deletePrimaryFormIcon
      description: >
        Delete the primary icon from the form.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      responses:
        204:
          description: Success - icon deleted.
  /api/events/{eventId}/icons/{formId}/{primary}/{variant}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/formIdInPath'
      - $ref: '#/components/parameters/primaryFieldValueInPath'
      - $ref: '#/components/parameters/variantFieldValueInPath'
    post:
      tags: [ Event ]
      operationId: uploadVariantFormIcon
      description: >
        Upload the icon image associated with the specified primary + variant
        field value combination.
      responses:
        200:
          $ref: '#/components/responses/FormIconInfo'
    get:
      tags: [ Event ]
      operationId: getVariantFormIcon
      description: >
        Get the variant icon for the specified form.  The requesting user must
        have `READ_EVENT_ALL` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          $ref: '#/components/responses/FormIconContent'
    delete:
      tags: [ Event ]
      operationId: deleteVariantFormIcon
      description: >
        Delete the variant icon from the form.  The requesting user  must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      responses:
        204:
          description: Success - icon deleted.
  /api/events/{eventId}/layers:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Layer ]
      operationId: getLayersForEvent
      description: >
        Return an array of all layers for specified event.
        The client must have 'READ_LAYER_ALL' permission of `READ_LAYER_EVENT`
        permission and an ACL entry on the event with `read` permission.
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum: [ Imagery, Feature, GeoPackage ]
      responses:
        200:
          description: Success - return an array of layer documents for specified event.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Layer'
    post:
      tags: [ Event ]
      operationId: addLayerToEvent
      description: >
        Add a layer to the specified event.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayerRef'
        required: true
      responses:
        200:
          description: Success - return the updated event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/events/{eventId}/layers/{layerId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/layerIdInPath'
    get:
      tags: [ Layer ]
      description: >
        Return the layer for the event specified with the ID specified
        in the path.  The requesting user must have `READ_LAYER_ALL` permission
        or `READ_LAYER_EVENT` permission and an ACL entry on the evebnt with
        `update` permission.
      operationId: getLayerForEventById
      responses:
        200:
          description: layer response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layer'
            application/octet-stream:
              schema:
                type: string
                format: binary
    delete:
      tags: [ Event ]
      operationId: removeLayerFromEvent
      description: >
        Remove the specified layer from the specified event.  The requesting
        user must have `UPDATE_EVENT` permission and an ACL entry on the event
        with `update` permission.
      responses:
        200:
          description: Success - return the updated event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/events/{eventId}/layers/{layerId}/{tableName}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/layerIdInPath'
    get:
      tags: [ Layer ]
      operationId: getXYZTileForGeoPackage
      description: >
        Get an XYZ map tile for the specified layer in the specified event.
      parameters:
        - in: path
          name: tableName
          description: GeoPackage table name
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success - XYZ map tile.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
                description: JPEG map tile
            pbf:
              schema:
                type: string
                format: binary
                description: Google protobuf vector tile

  /api/events/{eventId}/users:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Event ]
      operationId: getUsersForEvent
      description: >
        Get a flat list of all the users of all the teams with access to the
        specified event.  The requesting user must have `READ_EVENT_ALL`
        permission and an ACL entry on the event with `read` permission.
      responses:
        200:
          description: Success - return an array of user documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /api/events/{eventId}/teams:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    post:
      tags: [ Event ]
      operationId: addTeamToEvent
      description: >
        Add a team to the specified event.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.  All of the team's members will have access to the event.
      requestBody:
        description: >
          Document referencing the ID of the team to add to the event
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamRef'
        required: true
      responses:
        200:
          description: Success - return the updated event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    get:
      tags: [ Event ]
      operationId: getTeamsForEvent
      description: >
        Get the teams with access to the specified event.  The requesting user
        must have `READ_EVENT_ALL` permission and an ACL entry on the event
        with `read` permission.
      parameters:
        - in: query
          name: populate
          description: >
            The `populate` parameter is a comma-separated list of keys in the
            returned team documents to populate with their referenced documents.
            When the value of `populate` includes `users`, Mage will populate
            the returned team documents with the user documents they reference,
            replacing the `userIds` key in each team document with `users`.
          schema:
            type: string
            enum:
              - users
        - in: query
          name: omit_event_teams
          description: >
            Whether to omit the event's implicit team that Mage automatically
            creates for adding individual users to an event.
          schema:
            type: boolean
        - in: query
          name: term
          description: >
            Return teams whose name or description contains the given search term.
          schema:
            type: string
      responses:
        200:
          description: Success - return an array of team documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Team'
  /api/events/{eventId}/teams/{teamId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/teamIdInPath'
    delete:
      tags: [ Event ]
      operationId: removeTeamFromEvent
      description: >
        Remove the specified team from the specified event.  The requesting
        user must have `UPDATE_EVENT` permission and an ACL entry on the event
        with `update` permission.
      responses:
        200:
          description: Success - return the updated team document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/events/{eventId}/acl/{userId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/userIdInPath'
    put:
      tags: [ Event ]
      operationId: setUserAccessForEvent
      description: >
        Set the specified user's ACL role on the specified event.  The
        requesting user must have `UPDATE_EVENT` permission and an ACL entry on
        the event with `update` permission.
      requestBody:
        $ref: '#/components/requestBodies/ACLRoleUpdate'
      responses:
        200:
          description: Success - return the updated event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
    delete:
      tags: [ Event ]
      operationId: removeUserAccessFromEvent
      description: >
        Remove the specified user's ACL role from the specified event.  The
        requesting user must have `UPDATE_EVENT` permission and an ACL entry on
        the event with `update` permission.
      responses:
        200:
          description: Success - return the updated event document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/events/{eventId}/observations/id:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    post:
      tags: [ Observation ]
      operationId: createObservationId
      description: >
        Generate a new observation ID with which to save a new observation.
      responses:
        201:
          description: >
            Success - return a stub observation document including the `id`,
            `eventId`, and `url` properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
          links:
            createObservation:
              operationId: saveObservation
              parameters:
                eventId: $request.path.eventId
                ovservationId: $response.body#/id
  /api/events/{eventId}/observations/{observationId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    put:
      tags: [ Observation ]
      operationId: saveObservation
      description: >
        Create or update an observation with the specified observation ID for
        the specified event.  To create an observation, the requesting user
        must have `CREATE_OBSERVATION` permission and must be a member of a
        team with access to the event.  To update an observation, the
        requesting user must have `UPDATE_OBSERVATION_ALL` permission, or have
        `UPDATE_OBSERVATION_EVENT` permission as well as an ACL entry on the
        event with `read` permission, or be a member of a team with access to
        the event.
      requestBody:
        description: The observation properties
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservationIn'
        required: true
      responses:
        200:
          description: Success - return the updated observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
    get:
      tags: [ Observation ]
      operationId: getObservationById
      description: >
        Get the specified observation in the specified event.  The requesting
        user must have `READ_OBSERVATION_ALL` permission, or have
        `READ_OBSERVATION_EVENT` permission and an ACL entry on the event with
        `read` permission.
      parameters: &obsQueryParams
        - $ref: '#/components/parameters/observationQuery.fields'
        - $ref: '#/components/parameters/observationQuery.startDate'
        - $ref: '#/components/parameters/observationQuery.endDate'
        - $ref: '#/components/parameters/observationQuery.observationStartDate'
        - $ref: '#/components/parameters/observationQuery.observationEndDate'
        - $ref: '#/components/parameters/observationQuery.bbox'
        - $ref: '#/components/parameters/observationQuery.geometry'
        - $ref: '#/components/parameters/observationQuery.states'
        - $ref: '#/components/parameters/observationQuery.sort'
      responses:
        200:
          description: observation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
  /api/events/{eventId}/observations/{observationId}.zip:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    get:
      tags: [ Observation ]
      operationId: getObservationArchive
      description: >
        Get a zip archive of the specified observation content.  The requesting
        user must have `READ_OBSERVATION_ALL` permission, or have
        `READ_OBSERVATION_EVENT` permission and an ACL entry on the event with
        `read` permission.  The returned archive contains an entry named
        `<observation_id>/index.html`, as well as related resources for any
        media attached to the observation.
      responses:
        200:
          description: Success - return the observation zip archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/events/{eventId}/observations:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Observation ]
      description: >
        Get all the observations for the specified event that match the
        specified query parameters.  The requesting user must have
        `READ_OBSERVATION_ALL` permission, or have `READ_OBSERVATION_EVENT`
        permission and an ACL entry on the event with `read` permission.
      operationId: getObservationsForEvent
      # this used to be simply
      #   parameters: *obsQueryParams
      # referencing above, instead of the duplicated parameter array, but with
      # the update to js-yaml 4.1.x through openapi-enforcer, yaml anchors seem
      # to be broken
      parameters:
        - $ref: '#/components/parameters/observationQuery.fields'
        - $ref: '#/components/parameters/observationQuery.startDate'
        - $ref: '#/components/parameters/observationQuery.endDate'
        - $ref: '#/components/parameters/observationQuery.observationStartDate'
        - $ref: '#/components/parameters/observationQuery.observationEndDate'
        - $ref: '#/components/parameters/observationQuery.bbox'
        - $ref: '#/components/parameters/observationQuery.geometry'
        - $ref: '#/components/parameters/observationQuery.states'
        - $ref: '#/components/parameters/observationQuery.sort'
      responses:
        200:
          description: >
            Success - return the observation documents matching the query.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Observation'
  /api/events/{eventId}/observations/{observationId}/favorite:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    put:
      tags: [ Observation ]
      operationId: addObservationFavorite
      description: >
        Mark the specified observation as a favorite of the requesting user by
        adding the user's ID to the `favoriteUserIds` array on the observation.
        The requesting user must have `UPDATE_OBSERVATION_ALL` permission, or
        have `UPDATE_OBSERVATION_EVENT` permission and an ACL entry on the
        event with `read` permission.
      responses:
        200:
          description: Success - return the updated observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
    delete:
      tags: [ Observation ]
      operationId: removeObservationFavorite
      description: >
        Remove the requesting user's ID from the `favoriteUserIds` of the
        specified observation.  The requesting user must have
        `UPDATE_OBSERVATION_ALL` permission, or have `UPDATE_OBSERVATION_EVENT`
        permission and an ACL entry on the event with `read` permission.
      responses:
        200:
          description: Success - return the updated observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
  /api/events/{eventId}/observations/{observationId}/important:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    put:
      tags: [ Observation ]
      operationId: setObservationImportant
      description: >
        Mark the specified observation as important.  This operation allows
        administrators and event managers to flag important observations for
        all users with access to the event.  The requesting user must have
        `UPDATE_EVENT` permission and an ACL entry on the event with `update`
        permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservationImportantCreate'
        required: true
      responses:
        200:
          description: Success - return the updated observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
    delete:
      tags: [ Observation ]
      operationId: removeObservationImportant
      description: >
        Remove the important flag from the specified observation.  The
        requesting user must have `UPDATE_EVENT` permission and an ACL entry on
        the event with `update` permission.
      responses:
        200:
          description: Success - return the updated observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Observation'
  /api/events/{eventId}/observations/{observationId}/states:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    post:
      tags: [ Observation ]
      operationId: addObservationState
      description: >
        Set the current state of the specified observation.  The state is
        appended to a list of states on the observation, the head of which is
        the current state.  The requesting user must be the user that created
        the observation, have `UPDATE_EVENT` permission, or have an ACL entry on
        the event with `update` permission.
      requestBody:
        description: >
          The request body contains the name of the state to set on the
          target observation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservationStateCreate'
        required: true
      responses:
        201:
          description: Success - return the added state document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationState'
  /api/events/{eventId}/observations/{observationId}/attachments:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
    post:
      tags: [ Observation ]
      operationId: addAttachment
      description: >
        Add the given attachment to the specified observation.  The requesting
        user must have `UPDATE_OBSERVATION_ALL` permission, or have
        `UPDATE_OBSERVATION_EVENT` permission and an ACL entry on the event
        with `read` permission.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                attachment:
                  type: string
                  format: binary
              required:
                - attachment
        required: true
      responses:
        200:
          description: Success - return the attachment descriptor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
    get:
      tags: [ Observation ]
      operationId: getAttachments
      description: >
        Get the attachment descriptors for the specified observation.  The
        requesting user must have `READ_OBSERVATION_ALL` permission, or have
        `READ_OBSERVATION_EVENT` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          description: Success - return an array of attachment descriptors.
          content:
            application/octet-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Attachment'
  /api/events/{eventId}/observations/{observationId}/attachments/{attachmentId}:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
      - $ref: '#/components/parameters/observationIdInPath'
      - $ref: '#/components/parameters/attachmentIdInPath'
    put:
      tags: [ Observation ]
      operationId: updateAttachment
      description: >
        Update the specified attachment for the specified observation.  The
        requesting user must have `UPDATE_OBSERVATION_ALL` permission, or have
        `UPDATE_OBSERVATION_EVENT` permission and an ACL entry on the event
        with `read` permission.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                attachment:
                  type: string
                  format: binary
              required: [ attachment ]
        required: true
      responses:
        200:
          description: Success - return the updated attachment descriptor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
    get:
      tags: [ Observation ]
      operationId: getAttachment
      description: >
        Get the specified attachment content.  This operation returns the
        actual bytes of the attachment, not the attachment descriptor document.
        The requesting user must have `READ_OBSERVATION_ALL` permission, or have
        `READ_OBSERVATION_EVENT` permission and an ACL entry on the event with
        `read` permission.
      responses:
        200:
          description: attachment response
          content:
            '*/*':
              schema:
                type: string
                format: binary
    delete:
      tags: [ Observation ]
      operationId: deleteAttachment
      description: >
        Delete the specified attachment from the specified observation.  The
        requesting user must be the user that created the observation, have
        `UPDATE_EVENT` permission, or have an ACL entry on the event with
        `update` permission.
      responses:
        204:
          description: Success - the attachment was deleted.

  /api/events/{eventId}/feeds:
    parameters:
      - $ref: '#/components/parameters/eventIdInPath'
    get:
      tags: [ Feed ]
      operationId: listEventFeeds
      description: >
        Get a list of feeds associated with an event. Requires the
        `READ_EVENT_USER` permission.
      summary: Get feeds by event.
      responses:
        200:
          description: Success - return an array of feed documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Event not found
          content:
            application/json:
              schema:
                type: string
    post:
      tags: [ Feed ]
      operationId: addFeedToEvent
      description: >
        Add a feed to an event. Requires the `UPDATE_EVENT` permission.
      summary: Add a feed to an event.
      requestBody:
        description: >
          Event id and feed id to connect.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedAddToEvent'
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MageEvent'
        400:
          description: Missing feed id
          content:
            application/json:
              schema:
                type: string
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Event not found
          content:
            application/json:
              schema:
                type: string
  /api/events/{eventId}/feeds/{feedId}:
    parameters:
       - $ref: '#/components/parameters/eventIdInPath'
       - $ref: '#/components/parameters/feedIdInPath'
    delete:
      tags: [ Feed ]
      operationId: removeFeedFromEvent
      description: >
        Remove a feed from an event. Requires the `UPDATE_EVENT` permission.
      summary: Remove a feed from an event.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Feed' }
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Event not found
          content:
            application/json:
              schema:
                type: string
  /api/events/{eventId}/feeds/{feedId}/content:
    parameters:
       - $ref: '#/components/parameters/eventIdInPath'
       - $ref: '#/components/parameters/feedIdInPath'
    post:
      tags: [ Feed ]
      operationId: fetchFeedContent
      description: >
        Fetch feed content. Requires the `READ_EVENT_USER` permission.
      summary: Get a feeds content.
      requestBody:
        description: Variable params.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonObject'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedContent'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Event not found
          content:
            application/json:
              schema:
                type: string
  /api/feeds/service_types:
    get:
      tags: [ Feed ]
      operationId: listFeedServiceTypes
      description: >
        Get a list of feed service types.  Requires the `FEEDS_LIST_SERVICE_TYPES` permission.
      summary: Get a list of feed service types.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedServiceTypeDescriptor'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
  /api/feeds/service_types/{feedServiceTypeId}/topic_preview:
    parameters:
      - $ref: '#/components/parameters/feedServiceTypeIdInPath'
    post:
      tags: [ Feed ]
      operationId: previewFeedTopics
      description: >
        Preview feed topics.  Requires the `FEEDS_CREATE_SERVICE` permission.
      summary: Preview a feeds topic.
      requestBody:
        description: Service config.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceConfig'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedTopic'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service type not found
          content:
            application/json:
              schema:
                type: object
  /api/feeds/services:
    post:
      tags: [ Feed ]
      operationId: createFeedService
      description: >
        Create a feed service.  Requires the `FEEDS_CREATE_SERVICE` permission.
      summary: Create a feed service.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeedService'
      responses:
        201:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedService'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
    get:
      tags: [ Feed ]
      operationId: listFeedServices
      description: >
        List all feed services.  Requires the `FEEDS_LIST_SERVICES` permission.
      summary: Get a list of feed services.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedService'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
  /api/feeds/services/{feedServiceId}/topics:
    parameters:
      - $ref: '#/components/parameters/feedServiceIdInPath'
    get:
      tags: [ Feed ]
      operationId: listFeedServiceTopics
      description: >
        List feed service topics.  Requires `FEEDS_LIST_TOPICS` permission.
      summary: Get a list of feed service topics.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedTopic'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service not found
          content:
            application/json:
              schema:
                type: object
  /api/feeds/services/{feedServiceId}/topics/{feedTopicId}/feed_preview:
    parameters:
      - $ref: '#/components/parameters/feedServiceIdInPath'
      - $ref: '#/components/parameters/feedTopicIdInPath'
    post:
      tags: [ Feed ]
      operationId: previewFeedServiceTopic
      description: >
         Preview feed service topic.  Requires `FEEDS_CREATE_FEED` permission.
      summary: Get a preview of a feed service topic.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewFeedRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedPreview'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service or feed topic not found
          content:
            application/json:
              schema:
                type: object
  /api/feeds/services/{feedServiceId}/topics/{feedTopicId}/feeds:
    parameters:
      - $ref: '#/components/parameters/feedServiceIdInPath'
      - $ref: '#/components/parameters/feedTopicIdInPath'
    post:
      tags: [ Feed ]
      operationId: createFeed
      description: >
        Create feed.  Requires the `FEEDS_CREATE_FEED` permission.
      summary: Create a new feed.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feed'
      responses:
        201:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Entity not found
  /api/feeds/{feedServiceId}/feeds:
    parameters:
       - $ref: '#/components/parameters/feedServiceIdInPath'
    get:
      tags: [ Feed ]
      operationId: listServiceFeeds
      description: >
        List service feeds.  Requires the `FEEDS_LIST_ALL` permission.
      summary: Get a list of service feeds.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service not found
  /api/feeds/services/{feedServiceId}:
    parameters:
       - $ref: '#/components/parameters/feedServiceIdInPath'
    get:
      tags: [ Feed ]
      operationId: getFeedService
      description: >
        Get a feed service. Requires `FEEDS_LIST_SERVICES` permission.
      summary: Get a feed service.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedService'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service not found
    delete:
      tags: [ Feed ]
      operationId: deleteFeedService
      description: >
        Delete a feed service.  Requires the `FEEDS_CREATE_SERVICE` permission.
      summary: Delete a feed service.
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service not found.
  /api/feeds:
    get:
      tags: [ Feed ]
      operationId: listAllFeeds
      description: >
        List all feeds.  Requires `FEEDS_LIST_ALL` permission.
      summary: Get a list of feeds.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
  /api/feeds/service_types/{feedServiceTypeId}:
    parameters:
      - $ref: '#/components/parameters/feedServiceTypeIdInPath'
    get:
      tags: [ Feed ]
      operationId: getServiceType
      description: >
        Get a service type by id.  Requires `FEEDS_LIST_SERVICE_TYPES` permission.
      summary: Get a service type by id.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedServiceTypeDescriptor'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service type not found.
  /api/feeds/services/{feedServiceId}/topics/{feedTopicId}:
    parameters:
      - $ref: '#/components/parameters/feedServiceIdInPath'
      - $ref: '#/components/parameters/feedTopicIdInPath'
    get:
      tags: [ Feed ]
      operationId: getFeedTopic
      description: >
        Get a feed topic by id.  Requires `FEEDS_LIST_TOPICS` permission.
      summary: Get a feed topic.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedTopic'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed service or feed  topic not found.
  /api/feeds/{feedId}:
    parameters:
       - $ref: '#/components/parameters/feedIdInPath'
    get:
      tags: [ Feed ]
      operationId: getFeedById
      description: >
        Get a feed by id.  Requires `FEEDS_LIST_ALL` permission.
      summary: Get a feed.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
        404:
          description: Feed not found
    put:
      tags: [ Feed ]
      operationId: updateFeed
      description: >
         Update a feed.  Requires the `FEEDS_CREATE_FEED` permssion.
      summary: Update a feed.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feed'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        403:
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
    delete:
      tags: [ Feed ]
      operationId: deleteFeed
      description: >
        Delete a feed by id.  Requires the `FEEDS_CREATE_FEED` permssion.
      summary: Delete a feed.
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string

  /api/icons/{iconId}/content:
    parameters:
      - $ref: '#/components/parameters/iconIdInPath'
    get:
      tags: [ Icon ]
      operationId: getIconContent
      summary: Get an icons content.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaticIconWithContent'
        404:
          description: Icon not found
  /api/icons/{iconId}:
    parameters:
      - $ref: '#/components/parameters/iconIdInPath'
    get:
      tags: [ Icon ]
      operationId: getIconById
      summary: Get an icon.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaticIcon'
        404:
          description: Icon not found
  /api/icons:
    get:
      tags: [ Icon ]
      operationId: getIcons
      summary: Get all icons
      parameters:
        - in: query
          name: source_url
          schema:
            type: string
        - in: query
          name: page_size
          schema:
            type: integer
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: search
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfStaticIcons'

  /api/layers:
    get:
      tags: [ Layer ]
      operationId: getLayers
      description: >
        Return an array of all layers.  The client must have 'READ_LAYER_ALL' permission.
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum: [ Imagery, Feature, GeoPackage ]
      responses:
        200:
          description: Success - return an array of layer documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Layer'
    post:
      tags: [ Layer ]
      operationId: createLayer
      description: >
        Create a new layer. The requesting user must have `CREATE_LAYER`
        permission.
      requestBody:
        description: The new layer document
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayerCreate'
        required: true
      responses:
        201:
          description: Success - return the created event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layer'
  /api/layers/count:
    get:
      tags: [ Layer ]
      operationId: getLayerCount
      description: Return the number of layers in the database.
      responses:
        200:
          description: Success - return the layer count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
  /api/layers/{layerId}:
    parameters:
      - { $ref: '#/components/parameters/layerIdInPath' }
    get:
      tags: [ Layer ]
      description: >
        Return the layer with the ID specified in the path.  The requesting
        user must have `READ_LAYER_ALL` permission.
      operationId: getLayerById
      responses:
        200:
          description: layer response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layer'
            application/octet-stream:
              schema:
                type: string
                format: binary
    put:
      tags: [ Layer ]
      operationId: updateLayerById
      description: >
        Update the layer with the ID specified in the path.  The requesting
        user must have `UPDATE_LAYER` permission
      requestBody:
        description: layer update body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayerCreate'
        required: true
      responses:
        200:
          description: Success - return the update layer document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layer'
    delete:
      tags: [ Layer ]
      operationId: deleteLayer
      description: >
        Delete the event with the ID specified in the path.  The requesting
        user must have `DELETE_LAYER`.
      responses:
        204:
          description: Success - layer deleted
  /api/layers/{layerId}/features:
    parameters:
      - { $ref: '#/components/parameters/layerIdInPath' }
    get:
      tags: [ Layer ]
      operationId: getFeaturesForLayer
      description: >
        Return an array of features for specified layer.
        The requesting client must have `READ_LAYER_ALL`.
      responses:
        200:
          description: Success - return an arrary of features.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'geojson.yaml#/definitions/feature'
  /api/events/{eventId}/layers/{layerId}/features:
    parameters:
      - { $ref: '#/components/parameters/eventIdInPath' }
      - { $ref: '#/components/parameters/layerIdInPath' }
    get:
      tags: [ Layer ]
      operationId: getFeaturesForEventAndLayer
      description: >
        Return an array of features for specified layer for specified event.
        The requesting client must have `READ_LAYER_ALL` permission or
        `READ_LAYER_EVENT` and an ACL entry on the event with `read` permission.
      responses:
        200:
          description: Success - return an arrary of features.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'geojson.yaml#/definitions/feature'
  /api/events/{eventId}/locations:
    parameters:
      - { $ref: '#/components/parameters/eventIdInPath' }
    get:
      tags: [ Location ]
      operationId: getLocations
      description: >
        Return an array of locations for the specified event.
        The requesting client must have `READ_LOCATION_ALL` permission or
        `READ_LOCATION_EVENT` and an ACL entry on the event with `read` permission.
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
      - name: lastLocationId
        in: query
        description: locationId of last item in previous page (paging)
        schema:
          type: string
      - name: limit
        in: query
        description: limit locations (paging)
        schema:
          type: number
      responses:
        200:
          description: Success - array of user locations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'geojson.yaml#/definitions/feature'
    post:
      tags: [ Location ]
      operationId: createLocation
      description: >
        Create a new location for user with token in the specified event.
        The requesting client must have `CREATE_LOCATION` permission.
      requestBody:
        description: create location response
        content:
          application/json:
            schema:
              $ref: 'geojson.yaml#/definitions/feature'
        required: true
      responses:
        200:
          description: Success - the created location document.
  /api/events/{eventId}/locations/users:
    parameters:
      - { $ref: '#/components/parameters/eventIdInPath' }
    get:
      tags: [ Location ]
      operationId: getLocationsByUser
      description: >
        Return an array of user locations for the specified event.
        The requesting client must have `READ_LOCATION_ALL` permission or
        `READ_LOCATION_EVENT` and an ACL entry on the event with `read` permission.
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
      - name: lastLocationId
        in: query
        description: locationId of last item in previous page (paging)
        schema:
          type: string
      - name: limit
        in: query
        description: limit locations (paging)
        schema:
          type: number
      responses:
        200:
          description: Success - array of user locations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'geojson.yaml#/definitions/feature'
  /api/roles:
    get:
      tags: [ Role ]
      operationId: getRoles
      description: >
        Return an array of all roles.  The client must have `READ_ROLE` permission.
      responses:
        200:
          description: Success - an array of role documents.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Role' }
    post:
      tags: [ Role ]
      operationId: createRole
      description: >
        Create a new role. The client must have `CREATE_ROLE` permission.
      responses:
        200:
          description: Success - the created role document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
  /api/roles/{roleId}:
    parameters:
      - { $ref: '#/components/parameters/roleIdInPath' }
    get:
      tags: [ Role ]
      operationId: getRoleById
      description: >
        Return the role document whose `id` equals the `roleId` path parameter.
        The client must have `READ_ROLE` permission.
      responses:
        200:
          description: Success - role document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
    put:
      tags: [ Role ]
      operationId: updateRoleById
      description: >
        Update the user document whose `id` equals the `roleId` path parameter.
        The client must have `UPDATE_ROLE` permission.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoleIn' }
      responses:
        200:
          description: Success - The updated role document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
    delete:
      tags: [ Device ]
      description: >
        Delete a role document whose ID matches the path parameter for the
        role ID.  The requesting client must have `DELETE_ROLE` permission.
      operationId: deleteRoleById
      responses:
        200:
          description: Success - role deleted
  /api/settings:
    get:
      tags: [ Settings ]
      operationId: getSettings
      description: >
        Return an array of all the settings documents in the database.  The
        requesting client must have `READ_SETTINGS` permission.
      responses:
        200:
          description: Success - an array of settings documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Setting'
  /api/settings/{type}:
    get:
      tags: [ Settings ]
      operationId: getSettingByType
      description: >
        Return a settings document by the referenced `type`.  The
        requesting client must have `READ_SETTINGS` permission.
      parameters:
      - name: type
        in: path
        description: type name to update
        required: true
        schema:
          type: string
          enum:
          - banner
          - disclaimer
          - contactinfo
      responses:
        200:
          description: Success - setting document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
    put:
      tags: [ Settings ]
      operationId: updateSettingByType
      description: >
        Update the settings document whose `type` matches the type in the path.
        The requesting user must have `UPDATE_SETTINGS` permission.
      parameters:
      - name: type
        in: path
        description: type name to update
        required: true
        schema:
          type: string
          enum:
          - banner
          - disclaimer
          - contactinfo
      responses:
        200:
          description: Success - the update settings document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
  /api/exports/:
    get:
      tags: [ Export ]
      operationId: getAllExports
      description: >
        Get all exports regardless of user.
      summary: Get a list of all exports.
      responses:
        200:
          description: all exports.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Export' }
    post:
      tags: [ Export ]
      operationId: export
      description: >
        Export Mage data (GeoJSON, KML, GeoPackage, CSV) in the background. The requesting user must have
        `READ_OBSERVATION_ALL` permission or `READ_OBSERVATION_EVENT` or an ACL entry in the
        event with `read`.
      summary: Export Mage data using a background task.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
        required: true
      responses:
        201:
          description: export id
          headers:
            location:
              description: The URI of the export download.
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
  /api/exports/myself:
    get:
      tags: [ Export ]
      operationId: getExports
      description: >
        Get only exports for current token holder.
      summary: Get exports.
      responses:
        200:
          description: exports
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Export' }
  /api/exports/{exportId}:
    get:
      tags: [ Export ]
      operationId: getExportById
      description: >
        Download an export by id.
      summary: Download a completed export.
      parameters:
      - name: exportId
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: The exported data as a compressed file.
          content:
            application/zip:
              schema:
                type: object
components:
  securitySchemes:
    authenticationToken:
      type: http
      description: >
        Token generated after successful authentication.  The client will exchange
        this token with an approved device for and API token.
      scheme: bearer
      bearerFormat: JWT
    mageToken:
      type: http
      description: >
        Mage generates an API token when a client authenticates
        initially.  The client can use the token for subsequent requests until
        it expires.
      scheme: bearer
  schemas:
    CommaSeparatedTokens:
      type: string
      pattern: '\w+(,\w+)*'
    ColorHex:
      description: >
        This is a 3 or 4 byte hexadecimal string prefixed with '#' representing
        an RGB or RGBA color value, e.g. '#ff4545',
      type: string
      pattern: '#([a-fA-F0-9]{2}){3,4}'
    Count:
      type: object
      required: [ count ]
      properties:
        count:
          type: integer
    NormalizedRange:
      type: number
      format: float
      minimum: 0.0
      maximum: 1.0
    SortKey:
      description: >
        A `SortKey` is a string comprising the name of a document key,
        optionally suffixed with a sort direction modifier of `+DESC` or `+ASC`
        for descending or ascending, respectively.
      type: string
      pattern: ^\w+(\+(ASC|DESC))?
    User:
      description: >
        The `User` schema defines the structure of persisted user documents as
        they exist in the database and as the server returns them in various
        responses.
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        displayName:
          type: string
        status:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        active:
          type: boolean
        enabled:
          type: boolean
        avatarUrl:
          type: string
        iconUrl:
          type: string
        authentication:
          $ref: '#/components/schemas/AuthStatus'
        role:
          $ref: '#/components/schemas/Role'
        roleId:
          $ref: '#/components/schemas/Role/properties/id'
        icon:
          $ref: '#/components/schemas/UserIcon'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/Phone'
        recentEventIds:
          type: array
          items:
            $ref: '#/components/schemas/Event/properties/id'
      oneOf:
        - { type: object, required: [ role ], not: { type: object, required: [ roleId ] } }
        - { type: object, required: [ roleId ], not: { type: object, required: [ role ] } }
        - { type: object, not: { type: object, required: [ role, roleId ] } }
    UserRef:
      description: >
        `UserRef` is an object that references an existing user document with
        the required `id` property.  Mage ignores any properties other than
        `id`.
      type: object
      allOf:
        - { $ref: '#/components/schemas/User' }
        - { type: object, required: [ id ] }
    UserIn:
      type: object
      properties:
        username: { $ref: '#/components/schemas/User/properties/username' }
        displayName: { $ref: '#/components/schemas/User/properties/displayName' }
        email: { $ref: '#/components/schemas/User/properties/email' }
        phone:
          type: string
          format: phone
        roleId: { $ref: '#/components/schemas/User/properties/roleId' }
        iconMetadata:
          type: object
          properties:
            type: { $ref: '#/components/schemas/UserIcon/properties/type' }
            color: { $ref: '#/components/schemas/UserIcon/properties/color' }
            text: { $ref: '#/components/schemas/UserIcon/properties/text' }
        icon:
          description: >
            This key is valid only when encoded as `multipart/form-data`.
            This is a binary image file attachment.
          type: string
          format: binary
        avatar:
          description: >
            This key is valid only when encoded as `multipart/form-data`.
            This is a binary image file attachment.
          type: string
          format: binary
      allOf:
        - { $ref: '#/components/schemas/UserPasswordPair' }
    UserCreate:
      allOf:
        - { $ref: '#/components/schemas/UserIn' }
        - { type: object, required: [ username, displayName, password, passwordconfirm ] }
    UserUpdateSelf:
      allOf:
        - { $ref: '#/components/schemas/UserIn' }
        - type: object
          not:
            type: object
            required: [ password, passwordconfirm, icon, iconMetadata ]
    UserIcon:
      description: >
        A user icon is the small image that appears on a map to show the user's
        location.
      type: object
      properties:
        type:
          description: The origin of the icon
          type: string
          enum:
            - create
            - upload
            - none
        color:
          description: Color is only applicable for `create` type icons.
          $ref: '#/components/schemas/ColorHex'
        text:
          description: >
            Two-letter text label that appears on the map icon; only applies to
            `create` type icons
          type: string
        contentType:
          description: The MIME type of the icon image
          type: string
        size:
          description: The image size in bytes
          type: integer
    UserPasswordPair:
      type: object
      properties:
        password:
          type: string
        passwordconfirm:
          type: string
      oneOf:
        - { type: object, required: [ password, passwordconfirm ] }
        - { type: object, not: { type: object, required: [ password, passwordconfirm ] } }
    Authentication:
      type: object
      required:
        - user
        - token
      properties:
        user:
          $ref: '#/components/schemas/UserRef'
        token:
          type: string
    AuthStatus:
      type: object
      required:
        - type
      properties:
        type:
          type: string
        security:
          type: object
          properties:
            locked:
              type: boolean
            lockedUntil:
              type: string
              format: date-time
            invalidLoginAttempts:
              type: number
            numberOfTimesLocked:
              type: number
    ACL:
      description: >
        The ACL (Access Control List) is a mapping of user IDs to the roles and
        permissions users have to access the parent resource of the ACL.
      type: object
      additionalProperties:
        description: >
          The keys of the ACL object are user ID strings.  The values specify
          the role and permissions that the user matching the associated key
          has to access a resource.
        type: object
        properties:
          role: { $ref: '#/components/schemas/ACLRole' }
          permissions:
            description: >
              The permissions of an ACL entry are currently a static mapping
              from the role.  The ACL entry includes the permissions associated
              with the role to be more explicit about what the role means and
              how the user of the ACL entry can access the resource.
            type: array
            items: { $ref: '#/components/schemas/ACLPermission' }
    ACLRole:
      type: string
      enum:
        - OWNER
        - MANAGER
        - GUEST
    ACLPermission:
      type: string
      enum:
        - read
        - update
        - delete
    Device:
      required:
        - id
        - uid
        - name
        - description
      type: object
      properties:
        id:
          type: string
        uid:
          type: string
          description: >
            The device UID is an identifier string assigned at the application
            level.  This is usually a UUID, but can be any string the creator
            of the device chooses.
        name:
          type: string
        description:
          type: string
        registered:
          type: boolean
        userAgent:
          type: string
        appVersion:
          type: string
        userId:
          $ref: '#/components/schemas/User/properties/id'
        user:
          $ref: '#/components/schemas/User'
      oneOf:
        - { type: object, required: [ userId ], not: { type: object, required: [ user ] } }
        - { type: object, required: [ user ], not: { type: object, required: [ userId ] } }
    DeviceIn:
      type: object
      required: [ uid ]
      properties:
        uid:
          type: string
        name:
          type: string
        description:
          type: string
        appVersion:
          type: string
        userId:
          $ref: '#/components/schemas/User/properties/id'
    Team:
      description: >
        A team is simply a grouping of users that commonly operate together.
        Teams facilitate adding groups of users to events.
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        description:
          type: string
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
        teamEventId:
          $ref: '#/components/schemas/Event/properties/id'
          description: >
            Mage adds this property to indicate that a team is the implicitly
            created team paired with an event for grouping the event's users
            on an individual basis.  This property references the ID of the
            event document to which the team belongs.  To add an individual
            user to an event, add the user to the team with the `teamEventId`
            property that references the target event.
        acl:
          $ref: '#/components/schemas/ACL'
    TeamIn:
      type: object
      properties:
        name: { $ref: '#/components/schemas/Team/properties/name' }
        description: { $ref: '#/components/schemas/Team/properties/description' }
        users:
          type: array
          items: { $ref: '#/components/schemas/UserRef' }
    TeamCreate:
      allOf:
        - $ref: '#/components/schemas/TeamIn'
        - { type: object, required: [ name ] }
    TeamRef:
      allOf:
        - $ref: '#/components/schemas/Team'
        - { type: object, required: [ id ] }
    Event:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        complete:
          description: >
            When `true`, the `complete` flag indicates the event is no longer
            active.  One can reactivate a complete event at any time.
          type: boolean
        style:
          description: >
            The event's geometry style is the default style applied to each
            form of the event.  Individual forms can override the default
            style.
          $ref: '#/components/schemas/GeometryStyle'
        forms:
          type: array
          items:
            $ref: '#/components/schemas/Form'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/Team'
        layers:
          type: array
          items:
            $ref: '#/components/schemas/Layer'
        acl:
          $ref: '#/components/schemas/ACL'
    EventCreate:
      required:
        - name
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Event/properties/name'
        description:
          $ref: '#/components/schemas/Event/properties/description'
    EventUpdate:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Event/properties/name'
        description:
          $ref: '#/components/schemas/Event/properties/description'
        complete:
          $ref: '#/components/schemas/Event/properties/complete'
        forms:
          $ref: '#/components/schemas/Event/properties/forms'
    Form:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        color:
          $ref: '#/components/schemas/ColorHex'
          description: >
            The form's color is a visual discriminator that displays in the
            observation form selector when an event has multiple forms.
        primaryField:
          type: string
          description: >
            The primary field must be a single-select-type field whose choices
            determine the map symbology used to represent the observation on a
            map.
        variantField:
          type: string
          description: >
            The variant field must be another single-select-type field whose
            values can further refine the map symbology associated with the
            primary field's value of in an observation.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
          minItems: 1
        userFields:
          type: array
          items:
            $ref: '#/components/schemas/Field/properties/name'
          description: >
            A list of field names that will be drop-downs whose choices are
            dynamically populated with the names of users in the event.
    FormCreate:
      type: object
      allOf:
        - $ref: '#/components/schemas/Form'
        - type: object
          required: [ name, color, fields ]
    FormImport:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Form/properties/name'
        color:
          $ref: '#/components/schemas/Form/properties/color'
        form:
          type: string
          format: binary
          description: |
            The form is a zip file the user uploads.  THe layout of the zip
            file is the same as described in the `exportForm` operation.
      required: [ name, color, form ]
    GeometryStyle:
      type: object
      properties:
        strokeWidth:
          type: integer
        strokeOpacity:
          $ref: '#/components/schemas/NormalizedRange'
        stroke:
          type: string
    Field:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        title:
          type: string
        type:
          type: string
        value:
          type: string
        required:
          type: boolean
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
    Choice:
      type: object
      properties:
        id:
          type: number
        title:
          type: string
        value:
          type: string
    FormIcon:
      description: >
        `FormIcon` documents are the meta-data about icon images that Mage
        clients use to mark the location on the map display of observations
        with the associated form.
      type: object
      properties:
        eventId:
          $ref: '#/components/schemas/Event/properties/id'
        formId:
          $ref: '#/components/schemas/Form/properties/id'
        primary:
          type: string
          nullable: true
          description: >
            The value of the primary form field associated with the icon
        variant:
          type: string
          nullable: true
          description: >
            The value of the variant form field associated with the icon
        relativePath:
          type: string
          pattern: ^/\\d+/\\d+(/[^/]+){0,2}$
          description: >
            The relative path of the icon image URL, which looks like
            `<event_id>/<form_id>[/<primary>[/variant]]`
    FormIconEmbedded:
      allOf:
        - $ref: '#/components/schemas/FormIcon'
        - type: object
          properties:
            icon:
              type: string
              pattern: ^data:image/[^;]+;base64,[A-Za-z0-9+/]+$
              description: >
                The base-64-encoded image bytes of the icon, formatted as a
                data URL suitable for use as the value of the HTML `img` tag's
                `src` attribute
    FormIconUpload:
      type: object
      properties:
        icon:
          type: string
          format: binary
    Layer:
      title: Layer
      type: object
      properties:
        id:
          type: number
          description: The unique layer ID
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum: [ Feature, Imagery, GeoPackage ]
        url:
          type: string
        base:
          type: boolean
        format:
          type: string
          enum: [ WMS, XYZ, TMS ]
    WMSLayer:
      title: WMSLayer
      type: object
      properties:
        layers:
          type: string
          description: Comma separated list of WMS layer names
        styles:
          type: string
          description: Comma separated list of WMS style names
        format:
          type: string
          description: WMS map tile format.
        version:
          type: string
          description: WMS service version.
    LayerRef:
      allOf:
        - $ref: '#/components/schemas/Layer'
        - type: object
          required: [ id ]
    ObservationIn:
      description: >
        This schema defines the observation properties a client sends to save
        a new or updated observation.
      allOf:
        - $ref: 'geojson.yaml#/definitions/feature'
        - type: object
          properties:
            properties:
              $ref: '#/components/schemas/ObservationFeatureProperties'
        - type: object
          required: [ type, geometry, properties ]
    Observation:
      title: Observation
      description: >
        The `Observation` is the operative concept of Mage's geospatial data
        collection functionality.  Observation documents are the geo-tagged
        form and media records that Mage users submit to the Mage server.
        Observation documents are extensions of GeoJSON feature documents, so
        all observations have a `type` property whose value is `Feature`, as
        well as a `geometry` property that holds the geospatial geometry of the
        observation, such as point or polygon coordinates.  The values of the
        observation's form fields reside under the GeoJSON `properties` key.
      type: object
      properties:
        id:
          type: string
          description: The unique observation ID
        createdAt:
          type: string
          format: date-time
        lastModified:
          type: string
          format: date-time
        userId:
          $ref: '#/components/schemas/User/properties/id'
        deviceId:
          $ref: '#/components/schemas/Device/properties/id'
        eventId:
          $ref: '#/components/schemas/Event/properties/id'
        state:
          $ref: '#/components/schemas/ObservationState'
        url:
          type: string
          format: uri
          description: >
            This is the absolute URL of the observation where the client can
            fetch and update the observation document.
        favoriteUserIds:
          type: array
          items:
            $ref: '#/components/schemas/User/properties/id'
        attachements:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
      allOf:
        - $ref: '#/components/schemas/ObservationIn'
      example: {
        "createdAt": "2019-09-25T19:50:05.065Z",
        "deviceId": "5d697f88951c51a926e9dba4",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -0.08910298347473145,
            51.527068718503244
          ],
        },
        "lastModified": "2019-10-01T04:24:45.466Z",
        "properties": {
          "timestamp": "2019-09-25T19:48:55.859Z",
          "forms": [
            {
              "formId": 3,
              "field1": [
                "Umbarela"
              ],
            }
          ],
        },
        "type": "Feature",
        "userId": "5d697f88b8ed5f29bef7b10c",
        "favoriteUserIds": [
          "5d697f88b8ed5f29bef7b10c"
        ],
        "important": {
          "description": "Come back later",
          "timestamp": "2019-10-01T04:24:45.466Z",
          "userId": "5d697f88b8ed5f29bef7b10c"
        },
        "attachments": [
          {
            "contentType": "image/jpeg",
            "size": 24875,
            "name": "c1816efcab6e00c39623ddd8262b852e.jpg",
            "relativePath": "observations2/2019/9/25/c1816efcab6e00c39623ddd8262b852e.jpg",
            "lastModified": "2019-09-25T19:50:22.383Z",
            "oriented": false,
            "id": "5d8bc4fe038559417fffbb55",
            "url": "http://localhost:4242/api/events/2/observations/5d8bc4ed038559417fffbb53/attachments/5d8bc4fe038559417fffbb55"
          }
        ],
        "id": "5d8bc4ed038559417fffbb53",
        "eventId": 2,
        "url": "http://localhost:4242/api/events/2/observations/5d8bc4ed038559417fffbb53",
        "state": {
          "userId": "5d697f88b8ed5f29bef7b10c",
          "name": "active",
          "id": "5d8bc4ed038559417fffbb54",
          "url": "http://localhost:4242/api/events/2/observations/5d8bc4ed038559417fffbb53/states/5d8bc4ed038559417fffbb54"
        }
      }
    ObservationFeatureProperties:
      description: >
        This schema defines the specific keys that Mage recognizes under the
        GeoJSON feature's `properties` entry.
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        forms:
          type: array
          items:
            type: object
            properties:
              formId:
                $ref: '#/components/schemas/Form/properties/id'
            additionalProperties: true
      required: [ timestamp ]
    ObservationImportant:
      type: object
      properties:
        userId:
          $ref: '#/components/schemas/User/properties/id'
        timestamp:
          type: string
          format: date-time
        description:
          type: string
          description: The reason for flagging an observation important
    ObservationImportantCreate:
      allOf:
        - $ref: '#/components/schemas/ObservationImportant'
        - type: object
          required: [ description ]
    ObservationState:
      type: object
      properties:
        id:
          type: string
        name:
          $ref: '#/components/schemas/ObservationStateName'
        userId:
          $ref: '#/components/schemas/User/properties/id'
          description: >
            The ID of the user that set this state on the parent observation.
    ObservationStateCreate:
      allOf:
        - $ref: '#/components/schemas/ObservationState'
        - type: object
          required: [ name ]
    ObservationStateName:
      type: string
      enum: [ active, archive ]
      description: >
        Setting an observation's state to `archive` effectively deletes the
        observation from client views, but preserves the observation data.
    Attachment:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        relativePath:
          type: string
        contentType:
          type: string
        url:
          type: string
          format: uri
        oriented:
          type: boolean
    LocalCredentials:
      required:
        - password
        - username
      type: object
      properties:
        username:
          type: string
        password:
          type: string
    Thumbnail:
      type: object
      properties:
        name:
          type: string
        contentType:
          type: string
        height:
          type: number
        width:
          type: number
        size:
          type: number
        minDimension:
          type: number
    Phone:
      type: object
      properties:
        type:
          description: >
            The type of phone number currently defaults to `Main` and is
            static.
          type: string
        number:
          type: string
    LoginResponse:
      type: object
      properties:
        token:
          type: string
        expirationDate:
          type: string
        user:
          $ref: '#/components/schemas/User'
        role:
          $ref: '#/components/schemas/Role'
    Login:
      type: object
      properties:
        id:
          type: string
        timestamp:
          type: string
        device:
          $ref: '#/components/schemas/Device'
        deviceId:
          $ref: '#/components/schemas/Device/properties/id'
        user:
          $ref: '#/components/schemas/User'
        userId:
          $ref: '#/components/schemas/User/properties/id'
      required:
        - id
        - timestamp
      allOf:
        - oneOf:
          - { type: object, required: [ deviceId ], not: { type: object, required: [ device ] } }
          - { type: object, required: [ device ], not: { type: object, required: [ deviceId ] } }
        - oneOf:
          - { type: object, required: [ userId ], not: { type: object, required: [ user ] } }
          - { type: object, required: [ user ], not: { type: object, required: [ userId ] } }
    Role:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        permissions:
          type: array
          items:
            type: string
      required:
        - id
        - name
        - description
        - permissions
    RoleIn:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        permissions:
          type: array
          items:
            type: string
    LayerCreate:
      required:
        - name
        - type
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Layer/properties/name'
        description:
          $ref: '#/components/schemas/Layer/properties/description'
        type:
          $ref: '#/components/schemas/Layer/properties/type'
        url:
          $ref: '#/components/schemas/Layer/properties/url'
        base:
          $ref: '#/components/schemas/Layer/properties/base'
        format:
          $ref: '#/components/schemas/Layer/properties/format'
        wms:
          $ref: '#/components/schemas/WMSLayer'
        geopackage:
          type: string
          format: binary
          description: |
            The geopackage is a GeoPackage file the user uploads.  If uploading this file the `type` must
            be GeoPackage
    Setting:
      required:
        - type
      type: object
      properties:
        type:
          type: string
        settings:
          type: object
    Export:
      required:
        - type
      type: object
      properties:
        _id:
          type: string
        userId:
          $ref: '#/components/schemas/User/properties/id'
        physicalPath:
          type: string
        filename:
          type: string
        exportType:
          type: string
          enum: [ geojson, kml, geopackage, csv ]
        location:
          type: string
        status:
          type: string
        options:
          type: string
    AuthenticationConfiguration:
      required:
        - name
        - type
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        title:
          type: string
        textColor:
          type: string
        buttonColor:
          type: string
        icon:
          type: string
          format: byte
        enabled:
          type: boolean
        settings:
          type: object
    Style:
      properties:
        fill:
          $ref: '#/components/schemas/ColorHex'
        stroke:
          $ref: '#/components/schemas/ColorHex'
        fillOpacity:
          type: integer
          minimum: 0
          maximum: 1
        strokeOpacity:
          type: integer
          minimum: 0
          maximum: 1
        strokeWidth:
          type: integer
    SourceUrlStaticIconReference:
      required:
        - sourceUrl
      properties:
        sourceUrl:
          type: string
          format: uri
    RegisteredStaticIconReference:
      required:
        - id
      properties:
        id:
          type: string
    MapStyle:
      properties:
        stroke:
          $ref: '#/components/schemas/ColorHex'
        strokeOpacity:
          type: integer
          minimum: 0
          maximum: 1
        strokeWidth:
          type: integer
        fill:
          $ref: '#/components/schemas/ColorHex'
        fillOpacity:
          type: integer
          minimum: 0
          maximum: 1
        icon:
          $ref: '#/components/schemas/SourceUrlStaticIconReference'
    Feed:
      required:
        - id
        - service
        - topic
        - title
        - itemsHaveIdentity
        - itemsHaveSpatialDimension
      type: object
      properties:
        id:
          type: string
        service:
          type: string
        topic:
          type: string
        title:
          type: string
        summary:
          type: string
        icon:
          $ref: '#/components/schemas/RegisteredStaticIconReference'
        constantParams:
          type: object
        variableParamsSchema:
          type: object
        updateFrequencySeconds:
          type: integer
        itemsHaveIdentity:
          type: boolean
        itemsHaveSpatialDimension:
          type: boolean
        itemTemporalProperty:
          type: string
        itemPrimaryProperty:
          type: string
        itemSecondaryProperty:
          type: string
        mapStyle:
          $ref: '#/components/schemas/MapStyle'
        itemPropertiesSchema:
          type: object
    FeedAddToEvent:
      required:
        - feedId
      type: object
      properties:
        feedId:
          type: string
    JsonObject:
      required:
        - prop
      type: object
      properties:
        prop:
          type: string
        value:
          type: object
    MageEvent:
      required:
        - id
        - name
        - layerIds
        - feedIds
        - forms
        - style
        - acl
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        complete:
          type: boolean
        teamIds:
          type: array
          items:
            type: string
        teams:
          type: array
          items:
            $ref: '#/components/schemas/Team'
        layerIds:
          type: array
          items:
            type: string
        feedIds:
          type: array
          items:
            type: string
        forms:
          type: array
          items:
            $ref: '#/components/schemas/Form'
        style:
          $ref: '#/components/schemas/Style'
        acl:
          $ref: '#/components/schemas/ACL'
    FeedContent:
      required:
        - feed
        - topic
        - items
      properties:
        feed:
          type: string
        variableParams:
          $ref: '#/components/schemas/JsonObject'
        topic:
          type: string
        items:
          type: array
          items:
            type: object
        pageCursor:
          type: object
    UserSearchResult:
      properties:
        id:
          type: string
        username:
          type: string
        displayName:
          type: string
        email:
          type: string
        active:
          type: boolean
        enabled:
          type: boolean
        allPhones:
          type: string
    PageOfUsers:
      required:
        - totalCount
        - pageSize
        - pageIndex
        - items
      properties:
        totalCount:
          type: integer
        pageSize:
          type: integer
        pageIndex:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserSearchResult'
    FeedServiceTypeDescriptor:
      properties:
        id:
          type: string
        pluginServiceTypeId:
          type: string
        title:
          type: string
        summary:
          type: string
    ServiceConfig:
      properties:
        serviceConfig:
          type: object
    FeedTopic:
      required:
        - id
        - title
      properties:
        id:
          type: string
        title:
          type: string
        summary:
          type: string
        icon:
          $ref: '#/components/schemas/SourceUrlStaticIconReference'
        paramsSchema:
          type: object
        updateFrequencySeconds:
          type: integer
        itemsHaveIdentity:
          type: boolean
        itemsHaveSpatialDimension:
          type: boolean
        itemTemporalProperty:
          type: string
        itemPrimaryProperty:
          type: string
        itemSecondaryProperty:
          type: string
        mapStyle:
          $ref: '#/components/schemas/MapStyle'
        itemPropertiesSchema:
          type: string
    CreateFeedService:
      properties:
        serviceType:
          type: string
        config:
          type: object
        title:
          type: string
        summary:
          type: string
    FeedService:
      required:
        - id
        - serviceType
        - title
        - config
      properties:
        id:
          type: string
        serviceType:
          type: string
        title:
          type: string
        summary:
          type: string
        config:
          type: object
    FeedPreview:
      required:
        - feed
      properties:
        feed:
          $ref: '#/components/schemas/Feed'
        content:
          $ref: '#/components/schemas/FeedContent'
    PreviewFeedRequest:
      properties:
        skipContentFetch:
          type: boolean
        variableParams:
          $ref: '#/components/schemas/JsonObject'
    ImageSize:
      required:
        - width
        - height
      properties:
        width:
          type: number
        height:
          type: number
    StaticIcon:
      required:
        - sourceUrl
        - id
        - registeredTimestamp
      properties:
        sourceUrl:
          type: string
          format: uri
        id:
          type: string
        registeredTimestamp:
          type: number
        resolvedTimestamp:
          type: number
        imageType:
          type: string
          enum:
            - raster
            - vector
        mediaType:
          type: string
        sizePixels:
          $ref: '#/components/schemas/ImageSize'
        sizeBytes:
          type: number
        contentHash:
          type: string
        contentTimestamp:
          type: number
        title:
          type: string
        summary:
          type: string
        fileName:
          type: string
        tags:
          type: array
          items:
            type: string
    StaticIconWithContent:
      required:
        - iconInfo
        - iconContent
      properties:
        iconInfo:
          $ref: '#/components/schemas/StaticIcon'
        iconContent:
          type: object
    PageOfStaticIcons:
      required:
        - totalCount
        - pageSize
        - pageIndex
        - items
      properties:
        totalCount:
          type: integer
        pageSize:
          type: integer
        pageIndex:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/StaticIcon'
    ExportRequest:
      required:
        - exportType
        - eventId
        - observations
        - locations
      properties:
        exportType:
          $ref: '#/components/schemas/Export/properties/exportType'
        eventId:
          $ref: '#/components/schemas/Event/properties/id'
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        observations:
          type: boolean
        locations:
          type: boolean
        attachments:
          type: boolean
        favorites:
          type: boolean
        important:
          type: boolean

  parameters:
    userIdInPath:
      in: path
      name: userId
      description: The ID of the target user document
      required: true
      example: 5d0b2bfeeec24262f1a5fdf3
      schema: { $ref: '#/components/schemas/User/properties/id' }
    eventIdInPath:
      in: path
      name: eventId
      description: The ID of the target event document
      required: true
      example: 1234
      schema: { $ref: '#/components/schemas/Event/properties/id' }
    formIdInPath:
      in: path
      name: formId
      description: The ID of a form within an event
      required: true
      schema: { $ref: '#/components/schemas/Form/properties/id' }
    primaryFieldValueInPath:
      in: path
      name: primary
      description: The value of the primary form field
      required: true
      schema:
        type: string
    variantFieldValueInPath:
      in: path
      name: variant
      description: The value of the variant form field
      required: true
      schema:
        type: string
    layerIdInPath:
      in: path
      name: layerId
      description: The ID of the target layer document
      required: true
      schema: { $ref: '#/components/schemas/Layer/properties/id' }
    deviceIdInPath:
      in: path
      name: deviceId
      description: The ID of the target device document
      required: true
      schema: { $ref: '#/components/schemas/Device/properties/id' }
    roleIdInPath:
      in: path
      name: roleId
      description: The ID of the target role document
      required: true
      schema: { $ref: '#/components/schemas/Device/properties/id' }
    teamIdInPath:
      in: path
      name: teamId
      description: The ID of the target team document
      required: true
      schema: { $ref: '#/components/schemas/Team/properties/id' }
    observationIdInPath:
      in: path
      name: observationId
      description: The ID of the target observation document
      required: true
      schema: { $ref: '#/components/schemas/Observation/properties/id' }
    attachmentIdInPath:
      in: path
      name: attachmentId
      description: The ID of the target attachment document
      required: true
      schema: { $ref: '#/components/schemas/Attachment/properties/id' }
    observationQuery.fields:
      in: query
      name: fields
      description: >
        The form fields to project in the result observation documents (JSON)
      explode: false
      schema:
        type: array
        items:
          type: string
    observationQuery.startDate:
      in: query
      name: startDate
      schema:
        type: string
        format: date-time
      description: >
        The low end of the range for the observations' `lastModified`
        property
    observationQuery.endDate:
      in: query
      name: endDate
      schema:
        type: string
        format: date-time
      description: >
        The high end of the range for the observations' `lastModified`
        property
    observationQuery.observationStartDate:
      in: query
      name: observationStartDate
      schema:
        type: string
        format: date-time
      description: >
        The low end of the range for the observations' `timestamp`
        property
    observationQuery.observationEndDate:
      in: query
      name: observationEndDate
      schema:
        type: string
        format: date-time
      description: >
        The low end of the range for the observations' `lastModified`
        property
    observationQuery.bbox:
      in: query
      name: bbox
      description: >
        Bounding box array as a JSON string, e.g.
        `[xMin, yMin, xMax, yMax]`
      explode: false
      schema:
        $ref: 'geojson.yaml#/definitions/boundingBox'
    observationQuery.geometry:
      in: query
      name: geometry
      description: >
        A URL-encoded, stringified JSON object that is a GeoJSON geometry
        as defined in geojson.yaml#/definitions/geometryObject
      schema:
        type: string
        format: json
    observationQuery.states:
      in: query
      name: states
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ObservationStateName'
    observationQuery.sort:
      in: query
      name: sort
      description: >
        The `sort` query parameter is a comma-separated list of sort keys.
        Currently, this operation only supports sorting on the
        `lastModified` key.
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SortKey'
    authenticationConfigurationIdInPath:
      in: path
      name: id
      description: The id of the authentication configuration
      required: true
      schema:
        type: string
    authenticationConfigurationIncludeDisabled:
      in: query
      name: includeDisabled
      description: Flag to return disabled configs
      required: false
      schema:
        type: boolean
    feedIdInPath:
      in: path
      name: feedId
      description: The ID of the target feed document
      required: true
      example: abc1234
      schema: { $ref: '#/components/schemas/Feed/properties/id' }
    feedServiceTypeIdInPath:
      in: path
      name: feedServiceTypeId
      description: The ID of the feed service type
      required: true
      example: abc1234
      schema:
        type: string
    feedServiceIdInPath:
      in: path
      name: feedServiceId
      description: The ID of the target feed service document
      required: true
      example: abc1234
      schema: { $ref: '#/components/schemas/FeedService/properties/id' }
    feedTopicIdInPath:
      in: path
      name: feedTopicId
      description: The ID of the target feed topic document
      required: true
      example: abc1234
      schema: { $ref: '#/components/schemas/FeedTopic/properties/id' }
    iconIdInPath:
      in: path
      name: iconId
      description: The ID of the target icon document
      required: true
      example: abc1234
      schema: { $ref: '#/components/schemas/StaticIcon/properties/id' }

  responses:
    FormIconInfo:
      description: Return the meta-data about a form icon.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FormIcon'
    FormIconContent:
      description: >
        Return the form icon as a base-64-encoded string value within the icon
        meta-data document, or as a binary image.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FormIconEmbedded'
        image/*:
          schema:
            type: string
            format: binary

  requestBodies:
    DeviceIn:
      description: >
        A `DeviceIn` request body specifies the keys and values to save to a
        `Device` document in the database.
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/DeviceIn' }
        application/x-www-form-urlencoded:
          schema: { $ref: '#/components/schemas/DeviceIn' }
    FormIconUpload:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/FormIconUpload'
          encoding:
            icon:
              contentType: image/*
    ACLRoleUpdate:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              role:
                $ref: '#/components/schemas/ACLRole'
            required: [ role ]