openapi: 3.0.0 # ----------------------------------------------------------------------------- # API metadata # ----------------------------------------------------------------------------- info: title: Hypothesis API version: 2.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 2.0. **This version is experimental and breaking changes may occur without warning.** 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://hypothes.is/api # ----------------------------------------------------------------------------- # Reusable tags for grouping operations # ----------------------------------------------------------------------------- tags: - name: general - name: annotations - name: groups - name: memberships - name: profile - name: users # ----------------------------------------------------------------------------- # Reusable components # ----------------------------------------------------------------------------- components: # ------------------------- # Reusable parameters # ------------------------- parameters: PageNumber: name: "page[number]" in: query required: false description: Which page of results to get schema: type: int default: 1 minimum: 1 PageAfter: name: "page[after]" in: query required: false description: Get only annotations older than this date schema: type: string format: date-time PageSize: name: "page[size]" in: query required: false description: How many items to get per page schema: type: int default: 20 minimum: 1 maximum: 100 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:@` schema: type: string pattern: 'acct:^[A-Za-z0.9_][A-Za-z0-9._]{1,28}[A-Za-z0-9_]@.*$' # ------------------------- # 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' Membership: $ref: './schemas/membership.yaml#/Membership' MembershipCreate: $ref: './schemas/membership-create.yaml#/Membership' PaginationMeta: $ref: './schemas/pagination-meta.yaml#/PaginationMeta' # ----------------------------------------------------------------------------- # API OPERATIONS # ----------------------------------------------------------------------------- paths: # --------------------------------------------------------------------------- # Service Root # --------------------------------------------------------------------------- /: get: 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: 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: tags: - annotations summary: Search for annotations 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`. 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) schema: type: string format: uri - name: url in: query description: Alias of `uri` 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` 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*` This feature is experimental and the API may change. schema: type: string - name: user in: query example: acct:username@hypothes.is description: Limit the results to annotations made by the specified user. 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). This can be specified multiple times to retrieve multiple groups. 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`. 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`. 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` 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. schema: type: string - name: references in: query description: Returns annotations that are replies to this parent annotation ID. 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. 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: 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: 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: 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: 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: 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: 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' # --------------------------------------------------------------------------- # Annotation Moderation Operations: Change status # --------------------------------------------------------------------------- /annotations/{id}/moderation: # ---------------------------------------------------------- # PATCH annotations/{id}/moderation - Change the moderation_status of an annotation # ---------------------------------------------------------- patch: tags: - annotations summary: Moderate an annotation description: | Change the moderation status of an annotation. The authenticated user must be a moderator, admin or owner of the annotation's group. security: - ApiKey: [] parameters: - $ref: '#/components/parameters/AnnotationID' - name: moderation_status in: query schema: description: The new moderation status for the annotation. type: string enum: [APPROVED, PENDING, DENIED, SPAM] - name: current_moderation_status in: query schema: description: | The annotation's `moderation_status` as returned by the API when fetching this annotation. If this optional parameter is included then the moderation request will fail if the annotation's `moderation_status` does not match the given `current_moderation_status`. type: string enum: [APPROVED, PENDING, DENIED, SPAM] - name: annotation_updated in: query description: | The annotation's `updated` time as returned by the API when fetching this annotation. If the optional `annotation_updated` parameter is included then the moderation request will fail if the annotation's `updated` time does not match the given `annotation_updated` time. schema: type: string format: date-time responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Annotation' # --------------------------------------------------------------------------- # Operations on Group collections # --------------------------------------------------------------------------- /groups: # ----------------------------------------------------- # GET groups - Fetch a filtered list of Groups # ----------------------------------------------------- get: 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: 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: 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: 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' # --------------------------------------------------------------------------- # Operations on Group Membership # --------------------------------------------------------------------------- # --------------------------------------------------------------------------- # GET groups/{id}/members - Get group memberships # --------------------------------------------------------------------------- /groups/{id}/members: get: tags: - memberships summary: Get group memberships description: | Get a paginated list of all user memberships in a group. To get the memberships of a private group the authenticated user must be a member of the group. Getting the memberships of an open or restricted group does not require authentication. The returned memberships are sorted by joining date, oldest first. If the `page[number]` query param is included in the request then the response will be paginated. If there's no `page[number]` query param in the request then a legacy, un-paginated response format will be used. In the future this legacy un-paginated response format will be removed and the paginated response format will be used even when the `page[number]` query param is not present. parameters: - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/PageSize' security: - AuthClient: [] - ApiKey: [] - {} responses: '200': description: Success content: application/*json: schema: oneOf: - title: "Paginated" type: object properties: meta: description: "Metadata about this response." type: object properties: page: $ref: '#/components/schemas/PaginationMeta' data: description: "The list of memberships for the requested page." type: array items: $ref: '#/components/schemas/Membership' - title: "Unpaginated (deprecated)" type: array items: $ref: '#/components/schemas/Membership' /groups/{id}/members/{user}: # ---------------------------------------------------------- # GET groups/{id}/members/{user} - Get group membership # ---------------------------------------------------------- get: tags: - memberships summary: Get group membership description: Fetch a user's membership of a group. Authenticated user must have read access to the group. Does not require authentication for reading members of public groups. security: - ApiKey: [] - {} parameters: - $ref: '#/components/parameters/GroupID' - $ref: '#/components/parameters/UserID' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Membership' # ---------------------------------------------------------- # POST groups/{id}/members/{user} - Add user to group # ---------------------------------------------------------- post: tags: - memberships summary: Add member to group description: | Add a user as a member to a group. security: - AuthClient: [] parameters: - $ref: '#/components/parameters/GroupID' - $ref: '#/components/parameters/UserID' requestBody: required: false content: application/*json: schema: $ref: '#/components/schemas/MembershipCreate' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Membership' # ------------------------------------------------------------------------ # PATCH groups/{id}/members/{user} - Change a user's membership in a group # ------------------------------------------------------------------------ patch: tags: - memberships summary: Update membership description: | Update a user's membership in a group. To update *your own* membership you can use the alias `me` in place of `{user}`. This is equivalent to using your own user ID. security: - ApiKey: [] parameters: - $ref: '#/components/parameters/GroupID' - $ref: '#/components/parameters/UserID' requestBody: required: true content: application/*json: schema: $ref: '#/components/schemas/MembershipCreate' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Membership' # ---------------------------------------------------------- # DELETE groups/{id}/members/{user} - Remove user from group # ---------------------------------------------------------- delete: tags: - memberships summary: Remove member from group description: | Remove a user from a group. To remove *yourself* from a group you can use the alias `me` in place of `{user}`. This is equivalent to using your own user ID. security: - ApiKey: [] parameters: - $ref: '#/components/parameters/GroupID' - $ref: '#/components/parameters/UserID' responses: '204': $ref: '#/components/responses/NoContent' # --------------------------------------------------------------------------- # Group annotations # --------------------------------------------------------------------------- # --------------------------------------------------------------------------- # GET groups/{id}/annotations - List the annotations of group # --------------------------------------------------------------------------- /groups/{id}/annotations: get: tags: - groups summary: List annotations in a group description: | Get a paginated list of all annotations in a group. parameters: - $ref: '#/components/parameters/PageAfter' - $ref: '#/components/parameters/PageSize' - name: moderation_status in: query description: | Filter the annotations by their moderation status. If not specified, all annotations are returned. schema: type: string enum: [APPROVED, PENDING, DENIED, SPAM] security: - ApiKey: [] responses: '200': description: Success content: application/*json: schema: oneOf: - title: "Paginated" type: object properties: meta: description: "Metadata about this response." type: object properties: page: $ref: '#/components/schemas/PaginationMeta' data: description: "The list of annotations for the requested page." type: array items: $ref: '#/components/schemas/Annotation' # --------------------------------------------------------------------------- # Operations on the currently-authenticated user (Profile) # --------------------------------------------------------------------------- /profile: # ----------------------------------------------------- # GET profile - Retrieve user profile # ----------------------------------------------------- get: 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: 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: 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/User' # --------------------------------------------------------------------------- # Operations on single User Resources # --------------------------------------------------------------------------- /users/{user}: # ---------------------------------------------------------- # GET users/{user} -- Fetch a user by `userid` # ---------------------------------------------------------- get: 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: 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/User'