@ngageoint/mage.service 6.2.2

package/lib/docs/openapi.yaml

@@ -0,0 +1,4591 @@
+openapi: 3.0.1
+info:
+  title: MAGE (Mobile Awareness GEOINT Environment) 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:
+      tags: [ User ]
+      description: >
+        Return an array of all users.  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 seperated list of WMS layer names
+        styles:
+          type: string
+          description: Comma seperated 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 ]