While creating a new annotation permissions are not set correctly

[MihailGorceagEndava]

Using endpoint https://h.readthedocs.io/en/latest/api-reference/v1/#tag/annotations I want to create a new annotation.
I'm using API key as Bearer Token.
Request body looks like this:

Response data of registered annotation looks like this:

Permissions from response looks like this:

I want that annotation should be available for anyone, but instead it's private. Setting permissions explicitly in request body does not work.

[robertknight]

The permissions array is unfortunately misleading with respect to the flexibility of permissions that is currently supported. The only supported permissions are "shared with the group" or "private to the user who created the annotation". The API is structured this way rather than having just an is_shared property for historical reasons.

The allowed values for the read permission are either the userid that is creating the annotation, in which case the annotation is private, or group:{group} (Edit: Corrected to group:) where group is the ID of the group in which the annotation is being created. In your case, you need to set read to group:q5X6RWJ6.

To make an annotation accessible to everyone, whether they are a member of the group or not, the permissions for the whole group need to be set. The group in question (https://hypothes.is/groups/q5X6RWJ6/elife) is world-readable, so everyone can read annotations that are shared with the group.

Please let me know if this helps resolve your issue.

[MihailGorceagEndava]

@robertknight Thank you ! But instead of groupid:{group} it should be group:{group}. Have just created new annotation and it works as expected. Thank you very much

[robertknight]

Ah, indeed! - Thanks for the correction and confirmation. I'm going to close this issue as resolved, but we need to do a better job of documenting the allowed permissions, or simply exposing the supported values in a more natural way (eg. an is_shared property).