Piwik PRO User Groups API

The User Groups API from Piwik PRO — 6 operation(s) for user groups.

GitHub OpenAPI

Operations 10

GET /api/user-groups/v1 List user groups #
POST /api/user-groups/v1 Add user group #
GET /api/user-groups/v1/{user_group_id} Get user group #
PATCH /api/user-groups/v1/{user_group_id} Edit user group #
DELETE /api/user-groups/v1/{user_group_id} Delete user group #
POST /api/user-groups/v1/{user_group_id}/permissions Set permission group #
POST /api/user-groups/v1/{user_group_id}/relationships/users Add users to user group #
DELETE /api/user-groups/v1/{user_group_id}/relationships/users Remove users from user group #
GET /api/user-groups/v1/{user_group_id}/users Get user group members #
GET /api/user-groups/v1/{user_group_id}/users/excluded Get users excluded from group #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/piwik-pro:piwik-pro-user-groups-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

piwik-pro-user-groups-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Web User Groups API
  version: master
servers:
- url: https://{account}.piwik.pro
  variables:
    account:
      default: example
security:
- OAuth2ClientCredentials: []
tags:
- name: User Groups
paths:
  /api/user-groups/v1:
    get:
      summary: List user groups
      description: Lists user groups
      operationId: list_user_group_v1
      parameters:
      - in: query
        name: search
        description: Search phrase - search for user group name, ID or external ID
        required: false
        schema:
          type: string
      - in: query
        name: sort
        description: Sort field - can be reversed by adding dash before field name e.g (-name)
        required: false
        schema:
          type: string
          enum:
          - name
          - created_at
          - updated_at
          - -name
          - -created_at
          - -updated_at
          default: name
      - in: query
        name: limit
        description: Limits the number of returned user groups in response
        required: false
        schema:
          type: integer
          maximum: 1000
          default: 10
      - in: query
        name: offset
        description: Sets offset for list of items
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    description: Metadata of a listing
                    required:
                    - total
                    properties:
                      total:
                        type: integer
                        description: Total number of items
                        example: 1
                  data:
                    type: array
                    items:
                      allOf:
                      - type: object
                        required:
                        - id
                        - type
                        - attributes
                        properties:
                          type:
                            type: string
                            enum:
                            - ppms/user-group
                          id:
                            allOf:
                            - type: string
                              format: uuid
                              description: UUIDv4 identifier of an object
                              example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                            - readOnly: true
                          attributes:
                            type: object
                            required:
                            - name
                            - created_at
                            - updated_at
                            properties:
                              name:
                                description: User group name
                                type: string
                                example: Managers
                              created_at:
                                allOf:
                                - type: string
                                  format: date-time
                                  description: Timestamp of object's creation
                                  readOnly: true
                                - readOnly: true
                              updated_at:
                                allOf:
                                - type: string
                                  format: date-time
                                  description: Timestamp of object's last modification
                                  readOnly: true
                                - readOnly: true
                      - type: object
                        properties:
                          attributes:
                            type: object
                            properties:
                              external_id:
                                type: string
                                nullable: true
                                description: External (IDP) identifier of user group
                                example: external group id
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
    post:
      summary: Add user group
      description: Adds user group with unique name
      operationId: add_user_group_v1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - id
                  - type
                  - attributes
                  properties:
                    type:
                      type: string
                      enum:
                      - ppms/user-group
                    id:
                      allOf:
                      - type: string
                        format: uuid
                        description: UUIDv4 identifier of an object
                        example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                      - readOnly: true
                    attributes:
                      type: object
                      required:
                      - name
                      - created_at
                      - updated_at
                      properties:
                        name:
                          description: User group name
                          type: string
                          example: Managers
                        created_at:
                          allOf:
                          - type: string
                            format: date-time
                            description: Timestamp of object's creation
                            readOnly: true
                          - readOnly: true
                        updated_at:
                          allOf:
                          - type: string
                            format: date-time
                            description: Timestamp of object's last modification
                            readOnly: true
                          - readOnly: true
        description: Request data to add new user group
        required: true
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - id
                    - type
                    - attributes
                    properties:
                      type:
                        type: string
                        enum:
                        - ppms/user-group
                      id:
                        allOf:
                        - type: string
                          format: uuid
                          description: UUIDv4 identifier of an object
                          example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                        - readOnly: true
                      attributes:
                        type: object
                        required:
                        - name
                        - created_at
                        - updated_at
                        properties:
                          name:
                            description: User group name
                            type: string
                            example: Managers
                          created_at:
                            allOf:
                            - type: string
                              format: date-time
                              description: Timestamp of object's creation
                              readOnly: true
                            - readOnly: true
                          updated_at:
                            allOf:
                            - type: string
                              format: date-time
                              description: Timestamp of object's last modification
                              readOnly: true
                            - readOnly: true
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
  /api/user-groups/v1/{user_group_id}:
    get:
      summary: Get user group
      description: Gets specific user group details
      operationId: UserGroupDetails_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - type: object
                      required:
                      - id
                      - type
                      - attributes
                      properties:
                        type:
                          type: string
                          enum:
                          - ppms/user-group
                        id:
                          allOf:
                          - type: string
                            format: uuid
                            description: UUIDv4 identifier of an object
                            example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                          - readOnly: true
                        attributes:
                          type: object
                          required:
                          - name
                          - created_at
                          - updated_at
                          properties:
                            name:
                              description: User group name
                              type: string
                              example: Managers
                            created_at:
                              allOf:
                              - type: string
                                format: date-time
                                description: Timestamp of object's creation
                                readOnly: true
                              - readOnly: true
                            updated_at:
                              allOf:
                              - type: string
                                format: date-time
                                description: Timestamp of object's last modification
                                readOnly: true
                              - readOnly: true
                    - type: object
                      properties:
                        attributes:
                          type: object
                          properties:
                            external_id:
                              type: string
                              nullable: true
                              description: External (IDP) identifier of user group
                              example: external group id
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
    patch:
      summary: Edit user group
      description: Updates user group details
      operationId: edit_user_group_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  allOf:
                  - allOf:
                    - type: object
                      required:
                      - id
                      - type
                      - attributes
                      properties:
                        type:
                          type: string
                          enum:
                          - ppms/user-group
                        id:
                          allOf:
                          - type: string
                            format: uuid
                            description: UUIDv4 identifier of an object
                            example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                          - readOnly: true
                        attributes:
                          type: object
                          required:
                          - name
                          - created_at
                          - updated_at
                          properties:
                            name:
                              description: User group name
                              type: string
                              example: Managers
                            created_at:
                              allOf:
                              - type: string
                                format: date-time
                                description: Timestamp of object's creation
                                readOnly: true
                              - readOnly: true
                            updated_at:
                              allOf:
                              - type: string
                                format: date-time
                                description: Timestamp of object's last modification
                                readOnly: true
                              - readOnly: true
                    - type: object
                      properties:
                        attributes:
                          type: object
                          properties:
                            external_id:
                              type: string
                              nullable: true
                              description: External (IDP) identifier of user group
                              example: external group id
                  - type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: UUID of edited user group (must match `user_group_id` parameter)
                        example: 9a67f188-734c-4ba3-8769-912a7e59f3ff
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
    delete:
      summary: Delete user group
      description: Deletes user group
      operationId: delete_user_group_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
  /api/user-groups/v1/{user_group_id}/permissions:
    post:
      deprecated: true
      summary: Set permission group
      description: 'Please use Set user group permission for a given app or Set user group permission for a given meta site instead.


        Sets permission group to entity for user group'
      operationId: set_permission_group_for_user_group_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - attributes
                  properties:
                    type:
                      description: Resource type
                      type: string
                      enum:
                      - ppms/permissions/group
                    attributes:
                      type: object
                      required:
                      - entity_id
                      - group
                      properties:
                        entity_id:
                          type: string
                          format: uuid
                          description: UUIDv4 identifier of an object
                          example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                        group:
                          type: string
                          description: Permission group (for example `edit-publish` contains permissions `view`, `edit` and `publish`)
                          enum:
                          - no-access
                          - view
                          - edit
                          - edit-publish
                          - manage
        description: Request data to set permission group for user group
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
  /api/user-groups/v1/{user_group_id}/relationships/users:
    post:
      summary: Add users to user group
      description: Adds users to user group
      operationId: add_users_to_group_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        description: Resource type
                        type: string
                        enum:
                        - ppms/user
                      id:
                        type: string
                        format: uuid
                        description: UUIDv4 identifier of an object
                        example: 6edb1e3c-4c43-4760-ab76-682ad83146be
        description: Request data to add users to user group
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
    delete:
      summary: Remove users from user group
      operationId: remove_users_from_group_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        description: Resource type
                        type: string
                        enum:
                        - ppms/user
                      id:
                        type: string
                        format: uuid
                        description: UUIDv4 identifier of an object
                        example: 6edb1e3c-4c43-4760-ab76-682ad83146be
        description: Request data to remove users from user group
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
  /api/user-groups/v1/{user_group_id}/users:
    get:
      summary: Get user group members
      description: Gets user group members
      operationId: list_user_group_users_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      - in: query
        name: search
        description: Search phrase for searching users by email or user id
        required: false
        schema:
          type: string
      - in: query
        name: sort
        description: Sort field - can be reversed by adding dash before field name e.g (-email)
        required: false
        schema:
          type: string
          enum:
          - email
          - -email
          default: email
      - in: query
        name: limit
        description: Limits the number of returned items
        required: false
        schema:
          type: string
          default: 10
      - in: query
        name: offset
        description: Sets offset for list of items
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    description: Metadata of a listing
                    required:
                    - total
                    properties:
                      total:
                        type: integer
                        description: Total number of items
                        example: 1
                  data:
                    type: array
                    items:
                      type: object
                      description: User details
                      required:
                      - id
                      - type
                      - attributes
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: UUIDv4 identifier of an object
                          example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                        type:
                          type: string
                          description: Resource type
                          enum:
                          - ppms/user
                        attributes:
                          type: object
                          required:
                          - email
                          properties:
                            email:
                              type: string
                              format: email
                              description: User email
                              example: example@example.com
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
  /api/user-groups/v1/{user_group_id}/users/excluded:
    get:
      summary: Get users excluded from group
      description: Gets users excluded from given user group
      operationId: list_user_group_users_excluded_v1
      parameters:
      - in: path
        name: user_group_id
        required: true
        description: UUIDv4 identifier of given user group
        schema:
          type: string
          format: uuid
      - in: query
        name: search
        description: Search phrase for searching users by email or user id
        required: false
        schema:
          type: string
      - in: query
        name: sort
        description: Sort field - can be reversed by adding dash before field name e.g (-email)
        required: false
        schema:
          type: string
          enum:
          - email
          - -email
          default: email
      - in: query
        name: limit
        description: Limits the number of returned items
        required: false
        schema:
          type: string
          default: 10
      - in: query
        name: offset
        description: Sets offset for list of items
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    description: Metadata of a listing
                    required:
                    - total
                    properties:
                      total:
                        type: integer
                        description: Total number of items
                        example: 1
                  data:
                    type: array
                    items:
                      type: object
                      description: User details
                      required:
                      - id
                      - type
                      - attributes
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: UUIDv4 identifier of an object
                          example: 6edb1e3c-4c43-4760-ab76-682ad83146be
                        type:
                          type: string
                          description: Resource type
                          enum:
                          - ppms/user
                        attributes:
                          type: object
                          required:
                          - email
                          properties:
                            email:
                              type: string
                              format: email
                              description: User email
                              example: example@example.com
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      tags:
      - User Groups
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes: {}
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-api-checksum: f30b118d8e5a9d203105c80d9cf4000e1fd797fefe12353beea7e379e41e6e6c
x-provenance:
  method: searched
  source: https://developers.piwik.pro/reference
  harvested: '2026-11-16'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.piwik.pro/reference/_legacy_get_permission_groups_v2.md
  - https://developers.piwik.pro/reference/_legacy_set_permission_group_v2.md
  - https://developers.piwik.pro/reference/accessible_modules_for_users_batch.md
  - https://developers.piwik.pro/reference/add_apps_to_meta_site_v1.md
  - https://developers.piwik.pro/reference/add_meta_site_v1.md
  - https://developers.piwik.pro/reference/add_user_group_v1.md
  - https://developers.piwik.pro/reference/add_users_to_group_v1.md
  - https://developers.piwik.pro/reference/api_app_add_v2.md
  - https://developers.piwik.pro/reference/api_app_delete_v2.md
  - https://developers.piwik.pro/reference/api_app_edit_v2.md
  - https://developers.piwik.pro/reference/api_app_list_v2.md
  - https://developers.piwik.pro/reference/api_apps_details_v2.md
  - https://developers.piwik.pro/reference/api_apps_permissions_v2.md
  - https://developers.piwik.pro/reference/api_apps_user_group_permissions_v2.md
  - https://developers.piwik.pro/reference/api_delete_app_tracker_setting_v2.md
  - https://developers.piwik.pro/reference/api_edit_app_tracker_settings_v2.md
  - https://developers.piwik.pro/reference/api_edit_global_tracker_settings_v2.md
  - https://developers.piwik.pro/reference/api_get_app_by_url_tracker_settings_v2.md
  - https://developers.piwik.pro/reference/api_get_app_tracker_settings_v2.md
  - https://developers.piwik.pro/reference/api_get_global_tracker_settings_v2.md
  - https://developers.piwik.pro/reference/api_users_add_v2.md
  - https://developers.piwik.pro/reference/api_users_change_role_v2.md
  - https://developers.piwik.pro/reference/api_users_delete_v2.md
  - https://developers.piwik.pro/reference/api_users_edit_v2.md
  - https://developers.piwik.pro/reference/api_users_invited_v2.md
  - https://developers.piwik.pro/reference/api_users_list_v2.md
  - https://developers.piwik.pro/reference/api_users_me_change_password_v2.md
  - https://developers.piwik.pro/reference/api_users_me_details_v2.md
  - https://developers.piwik.pro/reference/api_users_me_edit_v2.md
  - https://developers.piwik.pro/reference/api_users_user_details_v2.md
  - https://developers.piwik.pro/reference/audit_log_entries_v1.md
  - https://developers.piwik.pro/reference/delete-audience.md
  - https://developers.piwik.pro/reference/delete-profile-by-identifier.md
  - https://developers.piwik.pro/reference/delete-settings-activation.md
  - https://developers.piwik.pro/reference/delete_api-analytics-v1-manage-annotation-user-id.md
  - https://developers.piwik.pro/reference/delete_api-analytics-v1-manage-goals-id.md
  - https://developers.piwik.pro/reference/delete_api-container-settings-v1-app-app-id-settings-setting-name.md
  - https://developers.piwik.pro/reference/delete_api-tag-v1-app-id-tags-tag-id.md
  - https://developers.piwik.pro/reference/delete_api-tag-v1-app-id-triggers-trigger-id.md
  - https://developers.piwik.pro/reference/delete_api-tag-v1-app-id-variables-variable-id.md
  - https://developers.piwik.pro/reference/delete_api-tag-v1-app-id-versions-version-id-debug-links-debug-link-id.md
  - https://developers.piwik.pro/reference/delete_meta_site_v1.md
  - https://developers.piwik.pro/reference/delete_user_group_v1.md
  - https://developers.piwik.pro/reference/deprecated_api_user_details_v2.md
  - https://developers.piwik.pro/reference/edit_meta_site_v1.md
  - https://developers.piwik.pro/reference/edit_user_group_v1.md
  - https://developers.piwik.pro/reference/get-audience.md
  - https://developers.piwik.pro/reference/get-audiences.md
  - https://developers.piwik.pro/reference/get-enum.md
  - https://developers.piwik.pro/reference/get-fetch-activation-usage-stats.md
  - https://developers.piwik.pro/reference/get-import-webhook-request.md
  - https://developers.piwik.pro/reference/get-integration-gads-app-conversion-actions.md
  - https://developers.piwik.pro/reference/get-integration-gads-app-customer-id.md
  - https://developers.piwik.pro/reference/get-integration-gads-app-user-lists.md
  - https://developers.piwik.pro/reference/get-log-activation-details.md
  - https://developers.piwik.pro/reference/get-log-activation-last-v3.md
  - https://developers.piwik.pro/reference/get-log-activation-last.md
  - https://developers.piwik.pro/reference/get-log-activation-stats.md
  - https://developers.piwik.pro/reference/get-log-audience-version-profile-count.md
  - https://developers.piwik.pro/reference/get-log-audience-version-profile-last-v3.md
  - https://developers.piwik.pro/reference/get-log-audience-version-profile-last.md
  - https://developers.piwik.pro/reference/get-log-import-webhook-requests-last-v3.md
  - https://developers.piwik.pro/reference/get-log-import-webhook-requests-last.md
  - https://developers.piwik.pro/reference/get-log-import-webhook-requests-stats.md


# --- truncated at 32 KB (43 KB total) ---
# Full source: https://artifacts.apis.io/piwik-pro/openapi/piwik-pro-user-groups-api-openapi.yml