Communities

B2INST Communities API

Community read, update, delete and logo endpoints accept a community UUID or slug. Member and invitation endpoints, and record review request bodies, require the community UUID.

Example setup and permissions

Set the host and a personal access token created on that instance:

export B2INST_HOST='b2inst-test.gwdg.de'
export ACCESS_TOKEN='<personal-access-token>'
export COMMUNITY_SLUG='eudat'

Use the lookup below to obtain COMMUNITY_ID for the community you intend to work with. Examples use jq to read or construct JSON. A token identifies your account; each endpoint also checks its permissions:

Operation	Required permissions
Search your communities	Authenticated account
Search community members	Community membership; visibility settings can limit the results
Search invitations	Community manager (owner, administrator or manager role)
Invite members or change their roles	Community manager authorized to manage the target role
Change membership visibility or leave	Your own membership, or appropriate community management permissions
Create a community	Site administration permission
Update community metadata or logo	Community owner or administrator
Delete a community	Community owner; no open requests may remain

Site superusers also have management access. Public reads may omit the token; reading restricted content requires authentication and permission. The public member list additionally follows the community’s member visibility policy.

Member request bodies below use user ID 1 only as an illustration. Replace it with the intended user’s actual ID; use your own user ID when leaving a community. Response examples are illustrative and may be abbreviated with ....

Choose a community for a record

Look up the community by its slug, such as eudat, and use the returned id in record submission examples. The community’s display name is in metadata.title.

curl -fsS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_SLUG" > community.json

COMMUNITY_ID=$(jq -er '.id' community.json)
jq '{id, slug, title: .metadata.title, access}' community.json

Community UUIDs and policies depend on the instance. Do not copy an example UUID without checking it on your instance.

Assigning a record to a community uses a separate record endpoint: POST /api/records/<record-id>/communities, with a body shaped as {"communities":[{"id":"<community-uuid>"}]}. Adding communities to a draft creation or metadata update body does not assign the community. The returned parent.communities.ids is an output field, not an editable metadata field.

For a draft, direct assignment depends on your permissions and the community’s submission and review policies. Check the response for processed[].directly_added and any errors, then read the draft to confirm parent.communities.ids before publishing. The review workflow instead sets receiver.community through PUT /api/records/<record-id>/draft/review, followed by POST /api/records/<record-id>/draft/actions/submit-review. A review receiver identifies the target community; it is not yet an accepted community association.

See the record API, direct publication example, and community review example for the complete workflows and permission requirements.

List all communities and search for communities

List all the communities based on search query

  HTTP method: GET

  URL path: /api/communities

  Required parameters: None

  Optional parameters: q, size, page, sort, type

  Status code on success: 200

  Returns: the list of communities (in JSON format) or an error message.

Command:

curl "https://$B2INST_HOST/api/communities"

Returns:

{
  "hits": {
    "hits": [
            {
        "id": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095",
        "created": "2025-10-27T11:13:15.629504+00:00",
        "updated": "2025-10-29T12:11:55.734130+00:00",
        "links": {
          "featured": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/featured",
          "self": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095",
          "self_html": "https://b2inst-test.gwdg.de/communities/eudat/",
          "settings_html": "https://b2inst-test.gwdg.de/communities/eudat/settings",
          "logo": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/logo",
          "rename": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/rename",
          "members": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members",
          "public_members": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members/public",
          "invitations": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/invitations",
          "requests": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/requests",
          "records": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/records",
          "membership_requests": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/membership-requests"
        },
        "revision_id": 6,
        "slug": "eudat",
        "metadata": {
          "title": "EUDAT",
          "description": "The big Eudat community. Use this community if no other is suited for you"
        },
        "access": {
          "visibility": "public",
          "members_visibility": "hidden",
          "member_policy": "open",
          "record_submission_policy": "open",
          "review_policy": "all",
          "record_restricted_policy": "restricted"
        },
        "custom_fields": {},
        "deletion_status": {
          "is_deleted": false,
          "status": "P"
        },
        "children": {
          "allow": false
        }
      },
      ...
    ],
    "total": 26
  },
  "aggregations": {
    "type": {
      "buckets": [
        {
          "key": "project",
          "doc_count": 1,
          "label": "Project",
          "is_selected": false
        }
      ],
      "label": "Type"
    },
    "visibility": {
      "buckets": [
        {
          "key": "public",
          "doc_count": 26,
          "label": "Public",
          "is_selected": false
        }
      ],
      "label": "Visibility"
    }
  },
  "sortBy": "newest",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/communities?page=1&size=25&sort=newest",
    "next": "https://b2inst-test.gwdg.de/api/communities?page=2&size=25&sort=newest"
  }
}

Get a community

Get a specific community with community id or community slug

  HTTP method: GET

  URL path: /api/communities/<community-id/community-slug>

  Required parameters: community-id/community-slug

  Status code on success: 200

  Returns: The community in JSON format.

Command:

curl "https://$B2INST_HOST/api/communities/eudat"

Returns:

{
  "id": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095",
  "created": "2025-10-27T11:13:15.629504+00:00",
  "updated": "2025-10-29T12:11:55.734130+00:00",
  "links": {
    "featured": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/featured",
    "self": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095",
    "self_html": "https://b2inst-test.gwdg.de/communities/eudat/",
    "settings_html": "https://b2inst-test.gwdg.de/communities/eudat/settings",
    "logo": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/logo",
    "rename": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/rename",
    "members": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members",
    "public_members": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members/public",
    "invitations": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/invitations",
    "requests": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/requests",
    "records": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/records",
    "membership_requests": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/membership-requests"
  },
  "revision_id": 6,
  "slug": "eudat",
  "metadata": {
    "title": "EUDAT",
    "description": "The big Eudat community. Use this community if no other is suited for you"
  },
  "access": {
    "visibility": "public",
    "members_visibility": "hidden",
    "member_policy": "open",
    "record_submission_policy": "open",
    "review_policy": "all",
    "record_restricted_policy": "restricted"
  },
  "custom_fields": {},
  "deletion_status": {
    "is_deleted": false,
    "status": "P"
  },
  "children": {
    "allow": false
  },
  "statistics": {
    "records": 1019,
    "files": 7766,
    "file_size": 1181466776793,
    "record_views": 7939,
    "record_downloads": 8620
  }
}

Search your communities

Search for communities you as a user belong based on a search query

  HTTP method: GET

  URL path: /api/user/communities

  Required parameters: None

  Optional parameters: q, size, page, sort, type

  Status code on success: 200

  Returns: A list of communities the user belong in JSON format.

Command:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/user/communities"

Returns:

{
  "hits": {
    "hits": [
      {
        "id": "ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483",
        "created": "2025-11-14T10:31:48.417481+00:00",
        "updated": "2025-11-14T10:41:32.464340+00:00",
        "links": {
          "featured": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/featured",
          "self": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483",
          "self_html": "https://b2inst-test.gwdg.de/communities/converge/",
          "settings_html": "https://b2inst-test.gwdg.de/communities/converge/settings",
          "logo": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/logo",
          "rename": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/rename",
          "members": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/members",
          "public_members": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/members/public",
          "invitations": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/invitations",
          "requests": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/requests",
          "records": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/records",
          "membership_requests": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/membership-requests"
        },
        "revision_id": 10,
        "slug": "converge",
        "metadata": {
          "title": "CONVERGE",
          "description": "Telecommunications and Computer Vision Convergence Tools for Research Infrastructures",
          "type": {
            "id": "project",
            "title": {
              "cs": "Projekt",
              "de": "Projekt",
              "en": "Project",
              "sv": "Projekt"
            }
          },
          "website": "https://converge-project.eu",
          "funding": [
            {
              "funder": {
                "id": "00k4n6c32",
                "name": "European Commission"
              },
              "award": {
                "id": "00k4n6c32::101094831",
                "number": "101094831",
                "title": {
                  "en": "Telecommunications and Computer Vision Convergence Tools for Research Infrastructures"
                },
                "identifiers": [
                  {
                    "identifier": "https://cordis.europa.eu/projects/101094831",
                    "scheme": "url"
                  }
                ],
                "acronym": "CONVERGE"
              }
            }
          ],
          "organizations": [
            {
              "id": "04m8m1253",
              "name": "CSC - IT Center for Science (Finland)",
              "identifiers": [
                {
                  "identifier": "04m8m1253",
                  "scheme": "ror"
                },
                {
                  "identifier": "grid.20709.3c",
                  "scheme": "grid"
                },
                {
                  "identifier": "0000 0004 0512 9137",
                  "scheme": "isni"
                }
              ]
            },
            ...
          ]
        },
        "access": {
          "visibility": "public",
          "members_visibility": "restricted",
          "member_policy": "open",
          "record_submission_policy": "closed",
          "review_policy": "closed",
          "record_restricted_policy": "restricted"
        },
        "custom_fields": {},
        "deletion_status": {
          "is_deleted": false,
          "status": "P"
        },
        "children": {
          "allow": false
        }
      }
    ],
    "total": 1
  },
  "aggregations": {
    "type": {
      "buckets": [
        {
          "key": "project",
          "doc_count": 1,
          "label": "Project",
          "is_selected": false
        }
      ],
      "label": "Type"
    },
    "visibility": {
      "buckets": [
        {
          "key": "restricted",
          "doc_count": 1,
          "label": "Restricted",
          "is_selected": false
        }
      ],
      "label": "Visibility"
    }
  },
  "sortBy": "newest",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/user/communities?page=1&size=25&sort=newest"
  }
}

Get community logo

Get the logo of a community.

  HTTP method: GET

  URL path: /api/communities/<community-id>/logo

  Required parameters: community-id

  Status code on success: 200

  Returns: The logo of a community.

Command:

curl "https://$B2INST_HOST/api/communities/eudat/logo"

Get community records

Get records in a specific community.

  HTTP method: GET

  URL path: /api/communities/<community-id>/records

  Required parameters: community-id

  Optional parameters: q, size, page, sort

  Status code on success: 200

  Returns: List of records in a community in JSON format.

Command:

curl "https://$B2INST_HOST/api/communities/eudat/records"

Returns:

{
  "hits": {
    "hits": [
      {record},
      ...
    ],
    "total": 1019
  },
  "aggregations": {
    "access_status": {
      "buckets": [
        {
          "key": "open",
          "doc_count": 906,
          "label": "Open",
          "is_selected": false
        },
        {
          "key": "restricted",
          "doc_count": 73,
          "label": "Restricted",
          "is_selected": false
        },
        {
          "key": "metadata-only",
          "doc_count": 37,
          "label": "Metadata-only",
          "is_selected": false
        },
        {
          "key": "embargoed",
          "doc_count": 3,
          "label": "Embargoed",
          "is_selected": false
        }
      ],
      "label": "Access status"
    },
    ...
  },
  "sortBy": "newest",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/communities/eudat/records?page=1&size=25&sort=newest",
    "next": "https://b2inst-test.gwdg.de/api/communities/eudat/records?page=2&size=25&sort=newest"
  }
}

Get community schema

Retrieves the latest JSON schema identifier for a specific community.

  HTTP method: GET

  URL path: /api/community-schema-extension/$COMMUNITY_SLUG

  Required parameters: None

  Status code on success: 200

  Returns: the community metadata schema id, embedded in a JSON object, or an error message.

Command:

curl -fsS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/community-schema-extension/$COMMUNITY_SLUG" > community-schema.json
SCHEMA_ID=$(jq -er '.uuid' community-schema.json)
cat community-schema.json

Returns:

{
  "url": "https://b2inst-test.gwdg.de/api/community-schema-extension/schema/$SCHEMA_ID/jsonschema",
  "uuid": "$SCHEMA_ID"
}

Retrieves the JSON schema using the schema UUID returned above, which is different from the community UUID. The community must have a metadata extension configured.

  HTTP method: GET

  URL path: /api/community-schema-extension/schema/$SCHEMA_ID/jsonschema

  Required parameters: None

  Status code on success: 200

  Returns: the community metadata schema, embedded in a JSON object, or an error message.

Command:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/community-schema-extension/schema/$SCHEMA_ID/jsonschema"

Returns:

{
  "id": "$SCHEMA_ID",
  "json_schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "description": "",
    "properties": {
      "metadata_url": {
        "description": "Metadata URL",
        "title": "Metadata URL",
        "type": "string"
      }
    },
    "title": "",
    "type": "object"
  },
  "version": 0
}

List all community schema extensions

List all community JSON schemas available.

  HTTP method: GET

  URL path: /api/community-schema-extension/

  Required parameters: None

  Status code on success: 200

  Returns: the community metadata schemas, or an error message.

Command:

curl "https://$B2INST_HOST/api/community-schema-extension/"

Returns:

[
  {
    "community_id": "c4234f93-da96-4d2f-a2c8-fa83d0775212",
    "community_schema_version": 1,
    "community_slug": "aalto",
    "schema_id": "36468ef3-30e6-4eee-ae0a-423b9911bac8",
    "section": "Aalto metadata"
  },
  {
    "community_id": "c4234f93-da96-4d2f-a2c8-fa83d0775212",
    "community_schema_version": 2,
    "community_slug": "aalto",
    "schema_id": "419e94c9-9c8b-4527-b12c-51fdd1f27947",
    "section": "Aalto metadata"
  },
  ...
]

Get community members

Get community members

  HTTP method: GET

  URL path: /api/communities/<community-id>/members

  Required parameters: community-id

  Optional parameters: q, size, page, sort, role

  Status code on success: 200

  Returns: The community members in JSON format.

This endpoint requires a community UUID and an authenticated community member.

Command:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/members"

Returns:

{
  "hits": {
    "hits": [
      {
        "id": "c10c3124-3bd4-4a0b-a7ee-647e3cab962c",
        "member": {
          "type": "user",
          "id": "1",
          "name": "B2share Superuser",
          "description": "",
          "avatar": "https://b2inst-test.gwdg.de/api/users/1/avatar.svg"
        },
        "role": "owner",
        "visible": false,
        "is_current_user": false,
        "permissions": {
          "can_leave": false,
          "can_delete": false,
          "can_update_role": false,
          "can_update_visible": false
        },
        "created": "2025-10-30T10:32:55.162430+00:00",
        "updated": "2025-10-30T10:43:54.047899+00:00",
        "revision_id": 3
      }
    ],
    "total": 1
  },
  "aggregations": {
    "role": {
      "buckets": [
        {
          "key": "owner",
          "doc_count": 1,
          "label": "Owner",
          "is_selected": false
        }
      ],
      "label": "Role"
    },
    "visibility": {
      "buckets": [
        {
          "key": "false",
          "doc_count": 1,
          "label": "Hidden",
          "is_selected": false
        }
      ],
      "label": "Visibility"
    }
  },
  "sortBy": "name",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members?page=1&size=25&sort=name"
  }
}

Search community public members

Get public members of a community based on a search query. Restricted communities, or member lists with members_visibility set to restricted, require a token for a community member. In a public community, individually public memberships can remain anonymously accessible even when members_visibility is hidden; see the member visibility limitation.

  HTTP method: GET

  URL path: /api/communities/<community-id>/members/public

  Required parameters: community-id

  Status code on success: 200

  Returns: The community members in JSON format.

Command:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/members/public"

Returns:

{
  "hits": {
    "hits": [
      {
        "id": "c10c3124-3bd4-4a0b-a7ee-647e3cab962c",
        "member": {
          "type": "user",
          "id": "1",
          "name": "B2share Superuser",
          "description": "",
          "avatar": "https://b2inst-test.gwdg.de/api/users/1/avatar.svg"
        },
        "role": "owner",
        "visible": true,
        "is_current_user": false,
        "permissions": {
          "can_leave": false,
          "can_delete": false,
          "can_update_role": false,
          "can_update_visible": false
        },
        "created": "2025-10-30T10:32:55.162430+00:00",
        "updated": "2025-10-30T10:43:54.047899+00:00",
        "revision_id": 3
      }
    ],
    "total": 1
  },
  "aggregations": {
    "role": {
      "buckets": [
        {
          "key": "owner",
          "doc_count": 1,
          "label": "Owner",
          "is_selected": false
        }
      ],
      "label": "Role"
    },
    "visibility": {
      "buckets": [
        {
          "key": "false",
          "doc_count": 1,
          "label": "Public",
          "is_selected": false
        }
      ],
      "label": "Visibility"
    }
  },
  "sortBy": "name",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/members?page=1&size=25&sort=name"
  }
}

Search invitations

Search invitations of a specific community

  HTTP method: GET

  URL path: /api/communities/<community-id>/invitations

  Required parameters: community-id

  Optional parameters: q, size, page, sort, role, status, is_open

  Status code on success: 200

  Returns: The community invitations in JSON format.

This endpoint requires a community UUID and community manager permissions.

Command:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/invitations"

Returns:

{
  "hits": {
    "hits": [],
    "total": 0
  },
  "aggregations": {
    "role": {
      "buckets": [],
      "label": "Role"
    },
    "status": {
      "buckets": [],
      "label": "Status"
    },
    "is_open": {
      "buckets": [],
      "label": "Status"
    }
  },
  "sortBy": "name",
  "links": {
    "self": "https://b2inst-test.gwdg.de/api/communities/ac1a12ab-95fc-40c3-ae5f-7f5bfe8e3483/members?page=1&size=25&sort=name"
  }
}

Invite members

Invite a member to a community

  HTTP method: POST

  URL path: /api/communities/<community-id>/invitations

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Request body

{
    "members":[
        {
            "id":"1",
            "type":"user"
        }
    ],
    "role":"reader",
    "message":"<p>Invitation message</p>"
}

Command:

curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"members":[{"id":"1","type":"user"}],"role":"reader","message":"<p>Invitation message</p>"}' \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/invitations"

Remove members and leave a community

Remove members from a community or leave a community

  HTTP method: DELETE

  URL path: /api/communities/<community-id>/members

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Request payload

{
    "members": [
        {
            "type": "user",
            "id": "1"
        }
    ]
}

Command:

curl -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"members":[{"type":"user","id":"1"}]}' \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/members"

Update members

Update members of a community

  HTTP method: PUT

  URL path: /api/communities/<community-id>/members

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Request body

{
    "members": [
        {
            "id": "1",
            "type": "user"
        }
    ],
    "visible": false,
    "role": "curator"
}

Command:

curl -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"members":[{"id":"1","type":"user"}],"visible":false,"role":"curator"}' \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/members"

Update invitation

Update an existing invitation to a community.

  HTTP method: PUT

  URL path: /api/communities/<community-id>/invitations

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Request body

{
    "members": [
        {
            "id": "1",
            "type": "user"
        }
    ],
    "role": "curator"
}

Command:

curl -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"members":[{"id":"1","type":"user"}],"role":"curator"}' \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/invitations"

For administrators

Create a new community

Create a community using a token for an account with site administration permission. Community membership or a community administrator role alone does not authorize creation.

  HTTP method: POST

  URL path: /api/communities

  Required parameters: None

  Status code on success: 201

  Returns: The created community in JSON format.

Save the following request body as new-community.json. Choose a unique slug containing only letters, numbers, underscores or hyphens. The example allows submissions and requires review; select policies appropriate for your community.

Request body:

{
  "slug": "example-instruments",
  "metadata": {
    "title": "Example instruments",
    "description": "Research instruments in the example community.",
    "organizations": [{"name": "EUDAT"}]
  },
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_submission_policy": "open",
    "review_policy": "closed"
  }
}

Use record_submission_policy to control submissions. The legacy record_policy field does not configure this setting in v3.

Command:

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @new-community.json \
  "https://$B2INST_HOST/api/communities" > created-community.json

--data-binary @new-community.json sends the file’s JSON contents. A value such as -d 'community-json' would send literal text, not a JSON object.

The response has the same structure as Get a community, with the new community’s ID, slug, metadata and links. After a successful creation, select this new community for subsequent examples:

COMMUNITY_ID=$(jq -er '.id' created-community.json)
COMMUNITY_SLUG=$(jq -er '.slug' created-community.json)
jq '{id, slug, metadata, access}' created-community.json

Update community metadata

Update a community using a token for its owner or a community administrator.

  HTTP method: PUT

  URL path: /api/communities/<community-id>

  Required parameters: community-id

  Status code on success: 200

  Returns: The updated community in JSON format.

Fetch the selected community, keep its writable fields, and change the description. This preserves the current metadata, policies and slug. A regular update cannot rename the community; changing its slug requires the separate rename endpoint.

Prepare the request body:

curl -fsS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID" > community-current.json

jq '{slug, metadata, access, custom_fields: (.custom_fields // {})}
    | .metadata.description = "Updated description."' \
  community-current.json > community-update.json

Send the resulting JSON file. Do not copy response-only properties such as id, links, revision_id or statistics into the update body.

Command:

curl --fail-with-body -sS -X PUT \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @community-update.json \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID"

The response has the same structure as Get a community, with the updated description and revision.

Delete a community

Soft-delete the selected community using an owner’s token (or a site superuser’s token). Open requests must be resolved first. This operation deletes the community; to leave it or remove a member, use the members endpoint.

  HTTP method: DELETE

  URL path: /api/communities/<community-id>

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Command:

curl -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" --data '{}' \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID"

The JSON body may be empty ({}) or contain optional deletion information, such as {"note":"Community no longer used"}. Success returns HTTP 204 with no response body.

Update community logo

Update the logo of a community

  HTTP method: PUT

  URL path: /api/communities/<community-id>/logo

  Required parameters: community-id

  Status code on success: 200

  Content-type: application/octet-stream

  Returns: The community logo file information in JSON format.

Command:

curl -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --upload-file ./image.png \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/logo"

Returns:

...

Delete community logo

Delete the logo of a community

  HTTP method: DELETE

  URL path: /api/communities/<community-id>/logo

  Required parameters: community-id

  Status code on success: 204

  Returns: No content

Command:

curl -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://$B2INST_HOST/api/communities/$COMMUNITY_ID/logo"

Last update : 08.10.2026

Last review : 08.10.2026