hypothesis-v1.yaml

openapi: 3.0.0
# -----------------------------------------------------------------------------
# API metadata
# -----------------------------------------------------------------------------
info:
  title: Hypothesis API
  version: 1.0.0
  termsOfService: https://hypothes.is/terms-of-service
  license:
    name: BSD (2-Clause)
    url: https://github.com/hypothesis/h/blob/master/LICENSE
  description: |

    # Hypothesis API

    This is a reference for the Hypothesis HTTP API version 1.0.

    See [the API overview](https://h.readthedocs.io/en/latest/api/)
    for an introduction to the API and information about other versions.

    ## Versions

    There are currently two versions of the Hypothesis API.

    * [v1: Stable](https://h.readthedocs.io/en/latest/api-reference/v1/) —
      This version is recommended for all users at this time
    * [v2: Experimental](https://h.readthedocs.io/en/latest/api-reference/v2/)

    By default, API requests will receive the **v1** version of the Hypothesis API.
    Though not required, we urge clients to set an `Accept` header with a media
    type corresponding to the desired version, e.g.

    ```
    Accept: application/vnd.hypothesis.v1+json
    ```

    If an `Accept` header is set with an unrecognized media type, the API will
    return an HTTP 406 (Not Acceptable) error.

    Responses to API requests include a header indicating which API version was used
    to handle the request, e.g.:

    ```
    Hypothesis-Media-Type: application/vnd.hypothesis.v1+json
    ```

    ## Authorization

    API requests which only read public data do not require authorization.

    Other requests need to be authenticated and authorized. To learn more, see:

    * [The Authentication section of this document](https://h.readthedocs.io/en/latest/api-reference/v1/#section/Authentication)
    * [Hypothesis API authorization documentation](https://h.readthedocs.io/en/latest/api/authorization)

    ## Expanding Resources

    Resources often contain links to related resources in their response bodies.
    Some endpoints support resource expansion, allowing those related resources
    to be expanded inline within the response.


    To expand resources (where supported), use the `expand` request parameter.
    Documentation for endpoints identify which resources are expandable, if any.

    ```
    GET /api/things?expand=organization&expand=foobar
    ```

    Values for `expand` are the fields to expand. The above would expand
    `organization` and `foobar` fields within the (hypothetical) returned `thing`
    objects. You can expand multiple fields by providing multiple values in the
    `expand` Array.

    ## Errors

    The API uses standard HTTP status codes to indicate the success or failure
    of requests. The body of the response will be JSON in the following format:

    ```
    {
      "status": "failure",
      "reason": "a human-readable string about what went wrong"
    }
    ```

    ### HTTP Status Codes

    Any API service may raise any of the following common errors.

    | Code        | Title         | Notes                                       |
    | ----------- | ------------- | ---------------------------------------------
    | 400         | Bad Request   | The server could not process the request because it was malformed |
    | 403         | Unauthorized  | v1 of the API only returns 404s, to avoid leaking resource existence |
    | 404         | Not Found     | Resource not found or permission failure    |
    | 409         | Conflict      | Resource could not be created because of a conflict—resource already exists |
    | 406         | Not Acceptable | The request's `Accept` header designates an unacceptable media type |
    | 500         | Server Error  | An error occurred with our API |

servers:
  - url: https://api.hypothes.is/api

# -----------------------------------------------------------------------------
# Reusable tags for grouping operations
# -----------------------------------------------------------------------------
tags:
  - name: general
  - name: annotations
  - name: groups
  - name: profile
  - name: users

# -----------------------------------------------------------------------------
# Reusable components
# -----------------------------------------------------------------------------
components:
  # -------------------------
  # Reusable parameters
  # -------------------------
  parameters:
    AnnotationID:
      name: id
      in: path
      required: true
      schema:
        description: The annotation's unique identifier
        type: string
    GroupID:
      name: id
      in: path
      required: true
      schema:
        description: |
          Either a unique identifier generated by the service or an authority-provided identifier
        oneOf:
          - type: string
            description: A short string — the group ID assigned by the service
            example: 4j7Dko3R
          - type: string
            pattern: "group:[a-zA-Z0-9._\\-+!~*()']{1,1024}@.*$"
            description: Unique identifier assigned by the group's owning authority
            example: 'group:338facc93@myauthority.net'
    GroupExpand:
      name: expand
      in: query
      required: false
      description: |
        One or more relations to expand for a group resource
      schema:
        type: array
        items:
          type: string
          enum:
            - organization
            - scopes
    Username:
      name: username
      in: path
      required: true
      description: |
        The user's username
      schema:
        type: string
    UserID:
      name: user
      in: path
      required: true
      description: |
        Unique identifier for a user, with specified authority.
        The userID should be of the format `acct:<username>@<authority>`
      schema:
        type: string
        pattern: 'acct:^[A-Za-z0-9._]{3,30}@.*$'

  # -------------------------
  # Reusable responses
  # -------------------------
  responses:
    NoContent:
      description: Success (No Content)
    BadRequest:
      description: Bad Request
      content:
        application/*json:
          schema:
            $ref: './schemas/errors.yaml#/Error'
    Conflict:
      description: Conflict
      content:
        application/*json:
          schema:
            $ref: './schemas/errors.yaml#/Error'
    NotFound:
      description: Not Found or Permission Denied
      content:
        application/*json:
          schema:
            $ref: './schemas/errors.yaml#/Error'
    NotAcceptable:
      description: Not Acceptable
      content:
        application/*json:
          schema:
            $ref: './schemas/errors.yaml#/Error'

  # --------------------------
  # Resusable security schemes
  # --------------------------
  securitySchemes:
    AuthClient:
      type: http
      scheme: basic
      description: |
        An AuthClient is a special registered set of credentials associated with a
        particular "authority", (typically formatted as a domain, e.g. `myauthority.com`).
        Requests authenticated in this manner allow the retrieval and manipulation
        of resources (e.g. users, groups) across an entire authority, not just for
        a single authenticated user.

        These credentials must be pre-registered with the service provider.

    AuthClientForwardedUser:
      type: apiKey
      in: header
      name: X-Forwarded-User
      description: |
        May only be used in conjunction with AuthClient authentication. Allows
        requests with AuthClient authentication to perform actions "on behalf of"
        users within the registered authority. The value of this header should be
        the userid of the intended forwarded user, e.g. `acct:username@myauthority.net`

    ApiKey:
      type: http
      scheme: bearer
      description: |
        An API key corresponds to a single user. Requests authenticated in this
        manner may retrieve and manipulate resources based on the authorization
        of the associated user.

  # ------------------------------
  # Resusable resource schemas
  # ------------------------------
  schemas:
    Annotation:
      $ref: './schemas/annotation.yaml#/Annotation'
    AnnotationCreate:
      $ref: './schemas/annotation-create.yaml#/Annotation'
    Group:
      $ref: './schemas/group.yaml#/Group'
    GroupCreate:
      $ref: './schemas/group-new.yaml#/Group'
    GroupUpdate:
      $ref: './schemas/group-update.yaml#/Group'
    Profile:
      $ref: './schemas/profile.yaml#/Profile'
    User:
      $ref: './schemas/user.yaml#/User'
    UserFull:
      $ref: './schemas/user.yaml#/UserFull'
    UserCreate:
      $ref: './schemas/user-new.yaml#/User'
    UserUpdate:
      $ref: './schemas/user-update.yaml#/User'

# -----------------------------------------------------------------------------
# API OPERATIONS
# -----------------------------------------------------------------------------
paths:
  # ---------------------------------------------------------------------------
  # Service Root
  # ---------------------------------------------------------------------------
  /:
    get:
      operationId: api
      tags:
        - general
      summary: Service root
      description: Provides a list of links to resources offered by the API.
      responses:
        '200':
          description: Success
      security: []

  # ---------------------------------------------------------------------------
  # Operations on Annotation collections
  # ---------------------------------------------------------------------------
  /annotations:
    # ---------------------------------------------------------------------------
    # POST annotations - Create an annotation
    # ---------------------------------------------------------------------------
    post:
      operationId: createAnnotation
      tags:
        - annotations
      summary: Create a new annotation
      security:
        - ApiKey: []
      requestBody:
        description: |
          Full representation of Annotation resource and applicable relationships.
          _Note_: While the API accepts arbitrary Annotation selectors in the
          `target.selector` property, the Hypothesis client currently supports
          `TextQuoteSelector`, `RangeSelector` and `TextPositionSelector` selector.
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/AnnotationCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'

  # ---------------------------------------------------------------------------
  # GET /search - Search annotations
  # ---------------------------------------------------------------------------
  /search:
    get:
      operationId: searchAnnotations
      tags:
        - annotations
      summary: Search for annotations
      security:
        - ApiKey: []
        - {} # Unauthenticated OK, depending on annotation status
      parameters:
        - name: limit
          in: query
          description: The maximum number of annotations to return.
          schema:
            type: integer
            minimum: 0
            default: 20
            maximum: 200
        - name: sort
          in: query
          schema:
            description: The field by which annotations should be sorted.
            type: string
            enum: [created, updated, group, id, user]
            default: updated
        - name: search_after
          in: query
          example: 2019-01-03T19:46:09.334539+00:00
          description: |
            Define a start point for a subset (page) of annotation search results.

            Working against the sorted, full set of annotation records matching the current
            search query, the service will examine the values present in the field by which
            annotations are sorted (i.e. `sort`). The returned subset
            of search results will begin with the first annotation whose `sort` field's value
            comes after the value of `search_after` sequentially.

            The format of this property depends on the current value of `sort`.
            When `search_after` is used in conjunction with a chronological `sort` value—e.g.
            `updated`, `created`—this parameter should be formatted as an ISO 8601 string. It
            may also be formatted in ms (milliseconds) since the Epoch.

            *Expanded example*

            Given a query containing a (URI-encoded) `search_after` value of `2019-01-03T19:46:09.334539+00:00`:

            >`sort=created&search_after=2019-01-03T19%3A46%3A09.334539%2B00%3A00`

            The returned results would begin with the record immediately subsequent to the annotation
            created at `2019-01-03T19:46:09.334539+00:00` in the full set of results. If there is no
            annotation in the full result set whose `created` value exactly matches
            `2019-01-03T19:46:09.334539+00:00`,

            the returned subset will begin with the first annotation whose `created` value
            comes sequentially "after" `2019-01-03T19:46:09.334539+00:00` in the full, sorted set.

            _Note:_ `search_after` provides an efficient, stateless paging mechanism. Its
            use is preferred over that of `offset`.
          required: false
          schema:
            type: string
        - name: offset
          in: query
          description: |
            The number of initial annotations to skip in the result set.

            May be used for pagination of result sets. The usage of `search_after` is preferred,
            especially for large batches, as it is considerably more efficient.
          schema:
            type: integer
            maximum: 9800
            default: 0
        - name: order
          in: query
          description: The order in which the results should be sorted.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: uri
          in: query
          description: |
            Limit the results to annotations matching the specific URI or equivalent URIs.

            URI can be a URL (a web page address) or a URN representing another kind of
            resource such as DOI (Digital Object Identifier) or a PDF fingerprint.

            Examples:

            * `http://example.com/articles/01/name` (URL)
            * `doi:10.1.1/1234` (DOI)
            * `urn:x-pdf:1234` (PDF fingerprint)
          required: false
          schema:
            type: string
            format: uri
        - name: url
          in: query
          description: Alias of `uri`
          required: false
          schema:
            type: string
            format: uri
        - name: uri.parts
          in: query
          example: 'yogur'
          description: |
            Limit the results to annotations containing the given keyword (tokenized chunk) in
            the URI. The value must exactly match an individual URI keyword.

            URIs are split on characters `#+/:=?.-` into their keywords.

            *Expanded example*

            Given a value of `yogur`, annotations with any of the following URIs would match:

            * `https://www.yogur.com/foo/bar`
            * `https://www.example.com/yogur/eatmore.html`
            * `https://www.example.com/foo/eat-more-yogur-this-year`

            The following would not be matches:

            * `https://www.yogurt.com/foo/bar`
            * `https://www.example.com/yogurt/eatmore.html`
            * `https://www.example.com/foo/eat-more-yogurt-this-year`

          required: false
          schema:
            type: string
        - name: wildcard_uri
          in: query
          example: 'http://foo.com/*'
          description: |
            Limit the results to annotations whose URIs match the wildcard pattern.

            `*` will match any character sequence (including an empty one),
            and a `_` will match any single character. Wildcards are only permitted
            within the path and query parts of the URI. Escaping wildcards is not supported.

            Examples of valid values:

            * `http://foo.com/*`
            * `urn:x-pdf:*`
            * `file://localhost/_bc.pdf`

            Examples of invalid values (not within path or query parts of URI):

            * `*foo.com`
            * `u_n:*`
            * `file://*`
            * `http://foo.com*`

            <mark>This feature is experimental and the API may change.</mark>
          required: false
          schema:
            type: string
        - name: user
          in: query
          example: acct:username@hypothes.is
          description: Limit the results to annotations made by the specified user.
          required: false
          schema:
            type: string
            pattern: 'acct:^[A-Z0-9._]{3,30}@.*$'
        - name: group
          in: query
          example: '8JmD3iz1'
          description: Limit the results to annotations made in the specified group (by group ID).
          required: false
          schema:
            type: string
        - name: tag
          in: query
          example: 'artificial intelligence'
          description: |
            Limit the results to annotations tagged with the specified value.

            For example: `artificial intelligence` will find all annotations whose tags
            contain both `artificial` **AND** `intelligence`.
          required: false
          schema:
            type: string
        - name: tags
          in: query
          example:
            - artificial
            - intelligence
          description: |
            Similar to `tag` but allows a comma-separated list of multiple tags.

            For example: `[intelligence,artificial]` will find all annotations whose tags
            contain both `artificial` **AND** `intelligence`.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: any
          in: query
          example: 'ribosome'
          description: |
            Limit the results to annotations who contain the indicated keyword
            in any of the following fields:

            * `quote`
            * `tags`
            * `text`
            * `url`
          required: false
          schema:
            type: string
        - name: quote
          in: query
          example: 'unicorn helmets'
          description: |
            Limit the results to annotations that contain this text inside
            the text that was annotated.

            For example: `unicorn helmets` would return all annotations containing
            `unicorn` **OR** `helmets` in their quoted (i.e. annotated) text.
          required: false
          schema:
            type: string
        - name: references
          in: query
          description: Returns annotations that are replies to this parent annotation ID.
          required: false
          schema:
            type: string
        - name: text
          in: query
          example: 'penguin strength'
          description: |
            Limit the results to annotations that contain this text in their
            textual body.

            For example: `penguin strength` would return all annotations containing
            `penguin` **OR** `strength` in their text (body) content.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - rows
                  - total
                properties:
                  rows:
                    type: array
                    items:
                      $ref: '#/components/schemas/Annotation'
                  total:
                    description: Total number of results matching query.
                    type: integer
  # ---------------------------------------------------------------------------
  # Operations on single Annotation resources
  # ---------------------------------------------------------------------------
  /annotations/{id}:
    # -----------------------------------------------------
    # GET annotations/{id} - Fetch an Annotation
    # -----------------------------------------------------
    get:
      operationId: fetchAnnotation
      tags:
        - annotations
      summary: Fetch an Annotation
      security:
        - ApiKey: []
        - {} # Unauthenticated OK, depending on annotation status
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'

    # ------------------------------------------------------------------
    # PATCH annotations/{id} - Update an Annotation (PUT also supported)
    # ------------------------------------------------------------------
    patch:
      operationId: updateAnnotation
      tags:
        - annotations
      summary: Update an Annotation
      description: |
        This endpoint is available under both the `PATCH` and `PUT`
        request methods. Both endpoints have PATCH-characteristics
        as defined in [RFC5789](https://tools.ietf.org/html/rfc5789#section-1),
        meaning the request body does not have to include the whole annotation
        object.

        New implementations should use the `PATCH` request method, and existing
        implementations continue to work under `PUT` but should switch to `PATCH`.
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'

    # ------------------------------------------------------------------
    # DELETE annotations/{id} - Delete an Annotation
    # ------------------------------------------------------------------
    delete:
      operationId: deleteAnnotation
      tags:
        - annotations
      summary: Delete an Annotation
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - deleted
                  - id
                properties:
                  deleted:
                    type: boolean
                    enum:
                      - true
                  id:
                    type: string

  # ---------------------------------------------------------------------------
  # Annotation Moderation Operations: Flagging
  # ---------------------------------------------------------------------------
  /annotations/{id}/flag:
    # --------------------------------------------------------
    # PUT annotations/{id}/flag - Add a flag to an annotation
    # --------------------------------------------------------
    put:
      operationId: flagAnnotation
      tags:
        - annotations
      summary: Flag an annotation
      description: |
        Flag an annotation for review (moderation). The moderator of the group
        containing the annotation will be notified of the flag and can decide
        whether or not to hide the annotation. Note that flags persist and
        cannot be removed once they are set.
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'

  # ---------------------------------------------------------------------------
  # Annotation Moderation Operations: Hiding/Unhiding
  # ---------------------------------------------------------------------------
  /annotations/{id}/hide:
    # ----------------------------------------------------------
    # PUT annotations/{id}/hide - Hide (moderate) an annotation
    # ----------------------------------------------------------
    put:
      operationId: hideAnnotation
      tags:
        - annotations
      summary: Hide an annotation
      description: |
        Hide an annotation. The authenticated user needs to have the moderate
        permission for the group that contains the annotation—this permission
        is granted to the user who created the group.
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'

    # ----------------------------------------------------------
    # DELETE annotations/{id}/hide - Unhide  an annotation
    # ----------------------------------------------------------
    delete:
      operationId: unhideAnnotation
      tags:
        - annotations
      summary: Show an annotation
      description: |
        Show/"un-hide" an annotation. The authenticated user needs to have the
        moderate permission for the group that contains the annotation—this
        permission is granted to the user who created the group.
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/AnnotationID'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'

  # ---------------------------------------------------------------------------
  # Operations on Group collections
  # ---------------------------------------------------------------------------

  /groups:
    # -----------------------------------------------------
    # GET groups - Fetch a filtered list of Groups
    # -----------------------------------------------------
    get:
      operationId: fetchGroupList
      tags:
        - groups
      summary: Get a list of Groups
      description: |
        Retrieve a list of applicable Groups, filtered by authority and target
        document (`document_uri`). Also retrieve user's private Groups.
      security:
        - ApiKey: []
        - {} # Unauthenticated OK

      parameters:
        - name: authority
          in: query
          description: |
            Filter returned groups to this authority. For authenticated requests,
            the user's associated authority will supersede any provided value.
          required: false
          schema:
            type: string
            default: 'hypothes.is'
        - name: document_uri
          in: query
          description: |
            Only retrieve public (i.e. non-private) groups that apply to a
            given document URI (i.e. the target document being annotated).
          required: false
          schema:
            type: string
            format: uri
        - $ref: '#/components/parameters/GroupExpand'

      responses:
        '200':
          description: Success
          content:
            application/*json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'

    post:
      operationId: createGroup
      tags:
        - groups
      summary: Create a new group
      description: |
        Create a new, private group for the currently-authenticated user.
      security:
        - AuthClientForwardedUser: []
        - ApiKey: []

      requestBody:
        description: Full representation of Group resource
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'

  # ---------------------------------------------------------------------------
  # Operations on individual Group resources
  # ---------------------------------------------------------------------------
  /groups/{id}:
    parameters:
      - $ref: '#/components/parameters/GroupID'

    # -----------------------------------------------------
    # GET groups/{id} - Fetch a Group
    # -----------------------------------------------------
    get:
      operationId: fetchGroup
      tags:
        - groups
      summary: Fetch a Group
      description: |
        Fetch a single Group resource.
      security:
        - AuthClient: []
        - ApiKey: []
        - {} # Unauthenticated OK
      parameters:
        - $ref: '#/components/parameters/GroupExpand'

      responses:
        '200':
          description: Success
          content:
            application/*json:
              schema:
                $ref: '#/components/schemas/Group'

    # -----------------------------------------------------
    # PATCH groups/{id} - Update a Group
    # -----------------------------------------------------
    patch:
      operationId: updateGroup
      tags:
        - groups
      summary: Update a Group
      description: |
        Update a Group resource.
      security:
        - AuthClient: []
        - AuthClientForwardedUser: []
        - ApiKey: []
      requestBody:
        description: Properties to update in Group resource
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/GroupUpdate'

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'

    # ---------------------------------------------------------------------
    # PUT groups/{id} - Replace (Create or Update) a Group, a.k.a. "upsert"
    # ---------------------------------------------------------------------
    put:
      operationId: upsertGroup
      tags:
        - groups
      summary: Create or Update a Group
      description: |
        Update the group with the indicated `id` or create one if it does
        not exist.
      security:
        - ApiKey: []
        - AuthClientForwardedUser: []
      requestBody:
        description: Full representation of Group resource
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'

  # ---------------------------------------------------------------------------
  # Operations on Group Membership
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # GET groups/{id}/members - Get group members
  # ---------------------------------------------------------------------------
  /groups/{id}/members:
    get:
      operationId: groupMembers
      tags:
        - groups
      summary: Get group members
      description: |
        Fetch a list of all members (users) in a group. Returned user resource only
        contains public-facing user data. Authenticated user must have read access
        to the group. Does not require authentication for reading members of
        public groups. Returned members are unsorted.
      security:
        - AuthClient: []
        - ApiKey: []
        - {} # Unauthenticated OK for public groups
      parameters:
        - $ref: '#/components/parameters/GroupID'
      responses:
        '200':
          description: Success
          content:
            application/*json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /groups/{id}/members/{user}:
    # ----------------------------------------------------------
    # POST groups/{id}/members/{user} - Add user to group
    # ----------------------------------------------------------
    post:
      operationId: addGroupMember
      tags:
        - groups
      summary: Add member to group
      description: |
        Add a user as a member to a group. This endpoint is only accessible to
        requests authenticated with `AuthClient` credentials and is restricted
        to users and groups within the associated authority.
      security:
        - AuthClient: []
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'

    # ----------------------------------------------------------
    # DELETE groups/{id}/members/{user} - Remove user from group
    # ----------------------------------------------------------
    delete:
      operationId: deleteGroupMember
      tags:
        - groups
      summary: Remove member from group
      description: |
        Remove a user from a group. At present, this endpoint only allows
        the removal as one's self (authenticated with API Key) from the
        indicated group.
      security:
        - ApiKey: []
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - name: user
          in: path
          description: Currently, only the literal value `me` is accepted
          required: true
          schema:
            type: string
            enum:
              - me
      responses:
        '204':
          $ref: '#/components/responses/NoContent'

  # ---------------------------------------------------------------------------
  # Operations on the currently-authenticated user (Profile)
  # ---------------------------------------------------------------------------
  /profile:
    # -----------------------------------------------------
    # GET profile - Retrieve user profile
    # -----------------------------------------------------
    get:
      operationId: userProfile
      tags:
        - profile
      summary: Fetch user's profile
      description: |
        Fetch profile information for the currently-authenticated user.
      security:
        - ApiKey: []
        - {} # Unauthenticated OK
      responses:
        '200':
          description: Success
          content:
            application/*json:
              schema:
                $ref: '#/components/schemas/Profile'

  /profile/groups:
    # -------------------------------------------------------------
    # GET user's groups - Retrieve groups for currently auth'd user
    # -------------------------------------------------------------
    get:
      operationId: userGroups
      tags:
        - profile
      summary: Fetch user's groups
      description: |
        Fetch the groups for which the currently-authenticated user is a member.
      security:
        - ApiKey: []
        - {} # Unauthenticated OK
      responses:
        '200':
          description: Success
          content:
            application/*json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'

  # ---------------------------------------------------------------------------
  # Operations on User Collections
  # ---------------------------------------------------------------------------
  /users:
    post:
      operationId: createUser
      tags:
        - users
      summary: Create a new user
      description: |
        Create a new user within the client's associated authority.
      security:
        - AuthClient: []

      requestBody:
        description: Full representation of User resource
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'

  # ---------------------------------------------------------------------------
  # Operations on single User Resources
  # ---------------------------------------------------------------------------
  /users/{user}:
    # ----------------------------------------------------------
    # GET users/{user} -- Fetch a user by `userid`
    # ----------------------------------------------------------
    get:
      operationId: userInfo
      tags:
        - users
      summary: Fetch a user
      description: |
        Fetch a single user. This endpoint is only accessible to
        requests authenticated with `AuthClient` credentials and is restricted
        to users within the associated authority.
      security:
        - AuthClient: []
      parameters:
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'

  /users/{username}:
    patch:
      operationId: updateUser
      tags:
        - users
      summary: Update a user
      description: |
        Update an existing user.
      security:
        - AuthClient: []

      parameters:
        - $ref: '#/components/parameters/Username'
      requestBody:
        description: Properties to update in the User resource
        required: true
        content:
          application/*json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'