> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an employee group

> Updates the name and categories together; if either is invalid, neither changes. Names are trimmed, contain 1–200 characters, and can be changed only for MANUAL and FILTER groups. Renaming SCIM or SYNCED groups returns 400. categoryIds replaces all categories for any group type with up to 100 active company category UUIDs. Repeated IDs are used once; an empty list removes all categories. Omitted properties keep their values; an empty object is accepted. Type, rules, membership, and sharing are unchanged. Requires permission to edit the group.



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json patch /c/{companyId}/groups/{groupId}
openapi: 3.1.0
info:
  title: Windmill API
  version: 2.0.0
  description: >-
    Use the Windmill API to integrate your systems, automate workflows, and
    build applications on your organization's data. Authenticate with an API key
    or OAuth access token. Each request uses the authenticated user's
    permissions within the selected workspace.
servers:
  - url: https://api.gowindmill.com/api/v2
security:
  - bearerAuth: []
paths:
  /c/{companyId}/groups/{groupId}:
    patch:
      tags:
        - Groups
      summary: Update an employee group
      description: >-
        Updates the name and categories together; if either is invalid, neither
        changes. Names are trimmed, contain 1–200 characters, and can be changed
        only for MANUAL and FILTER groups. Renaming SCIM or SYNCED groups
        returns 400. categoryIds replaces all categories for any group type with
        up to 100 active company category UUIDs. Repeated IDs are used once; an
        empty list removes all categories. Omitted properties keep their values;
        an empty object is accepted. Type, rules, membership, and sharing are
        unchanged. Requires permission to edit the group.
      operationId: groups.update
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              Company ID. A URL slug is also accepted. The caller must have
              access to this company.
            title: Company ID
            example: company-acme
          required: true
          description: >-
            Company ID. A URL slug is also accepted. The caller must have access
            to this company.
          name: companyId
          in: path
        - schema:
            type: string
            description: Opaque employee group identifier in this company.
            title: Employee group ID
            example: group-engineering
          required: true
          description: Opaque employee group identifier in this company.
          name: groupId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmployeeGroupRequest'
      responses:
        '200':
          description: Update group details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeGroupMutationResponse'
        '400':
          description: Bad request or request validation failed
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - BAD_REQUEST
                          message:
                            type: string
                          requestId:
                            type: string
                        required:
                          - code
                          - message
                          - requestId
                    required:
                      - error
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - VALIDATION_ERROR
                          message:
                            type: string
                          requestId:
                            type: string
                          details:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: array
                                  items:
                                    anyOf:
                                      - type: string
                                      - type: number
                                message:
                                  type: string
                              required:
                                - path
                                - message
                        required:
                          - code
                          - message
                          - requestId
                          - details
                    required:
                      - error
        '401':
          description: >-
            Authentication is missing or invalid. Send a valid API key or OAuth
            access token in the Authorization: Bearer <TOKEN> header before
            retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - UNAUTHORIZED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - FORBIDDEN
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - NOT_FOUND
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '429':
          description: >-
            The API-client request budget is exhausted. API keys allow 500
            requests per minute per key; OAuth clients allow 500 per minute per
            client and workspace. Reads and writes share the budget. One HTTP
            request counts once, including bulk requests. Wait for the
            Retry-After delay before retrying.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              required: true
              schema:
                type: integer
                minimum: 0
                example: 42
            RateLimit:
              description: >-
                Current request budget: limit is the maximum count, remaining is
                the unused count, and reset is seconds until the window resets,
                not a timestamp.
              required: true
              schema:
                type: string
                example: limit=500, remaining=0, reset=42
            RateLimit-Policy:
              description: >-
                Request limit and window length in seconds, formatted as
                <limit>;w=<seconds>.
              required: true
              schema:
                type: string
                example: 500;w=60
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - RATE_LIMITED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    UpdateEmployeeGroupRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Group name, trimmed, 1–200 characters. Duplicate group names are
            permitted.
          title: Group name
          example: Engineering
        categoryIds:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 100
          description: >-
            Replacement list of up to 100 active category UUIDs. Duplicate IDs
            are deduplicated. Omit to keep existing categories; an empty list
            removes all categories.
          title: Category IDs
          example:
            - 11111111-1111-4111-8111-111111111111
      title: Update employee group
      description: >-
        Updates name and categories together. Names are editable for MANUAL and
        FILTER groups; categories are editable for every group type. Omitted
        properties are unchanged.
      example:
        name: Product Engineering
        categoryIds:
          - 11111111-1111-4111-8111-111111111111
    EmployeeGroupMutationResponse:
      type: object
      properties:
        success:
          type: boolean
          description: True when the command completed successfully.
          title: Success
          example: true
      required:
        - success
      title: Group command response
      description: Confirmation that the command completed.
      example:
        success: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key or OAuth access token. Enter only the token in the
        authorization dialog; requests send it as `Authorization: Bearer
        <TOKEN>`.


        Create an API key in your workspace's **Settings → API keys**. Keys
        start with `wm_api_` and only work in the workspace where they were
        created. Read-only keys can read data; creating, updating, or deleting
        data requires a read-write key.


        ```http

        Authorization: Bearer wm_api_example

        ```


        OAuth access tokens are issued for connected Windmill applications.


        ```http

        Authorization: Bearer <OAUTH_ACCESS_TOKEN>

        ```


        Both token types use the authenticated user's workspace permissions.
        Each endpoint's permission requirements and the sharing settings of the
        requested items still apply.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.