> ## 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.

# List employee group categories

> Lists all active categories in the company, optionally filtered by a trimmed, case-insensitive name search. Categories are shared company-wide. groupCount includes only non-archived groups you can read; employeeCount counts distinct non-archived employees across those groups. Returns all matches without pagination, sorted by case-insensitive name, then ID. Categories with no groups you can read are included with zero counts.



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json get /c/{companyId}/groups/categories
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/categories:
    get:
      tags:
        - Group categories
      summary: List employee group categories
      description: >-
        Lists all active categories in the company, optionally filtered by a
        trimmed, case-insensitive name search. Categories are shared
        company-wide. groupCount includes only non-archived groups you can read;
        employeeCount counts distinct non-archived employees across those
        groups. Returns all matches without pagination, sorted by
        case-insensitive name, then ID. Categories with no groups you can read
        are included with zero counts.
      operationId: groups.categories.list
      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: >-
              Optional search text. Group and category names use a
              case-insensitive substring match.
            title: Search text
            example: Engineering
          required: false
          description: >-
            Optional search text. Group and category names use a
            case-insensitive substring match.
          name: query
          in: query
      responses:
        '200':
          description: Group categories by name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmployeeGroupCategoriesResponse'
        '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:
    ListEmployeeGroupCategoriesResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeGroupCategory'
          description: Active company categories, ordered by case-insensitive name then ID.
          title: Categories
          example:
            - id: 11111111-1111-4111-8111-111111111111
              name: Teams
              description: Organizational teams.
              icon:
                emoji: 👥
                color: '#3B82F6'
              groupCount: 1
              employeeCount: 1
              createdByEmployeeId: employee-avery
              createdAt: '2026-01-15T10:00:00.000Z'
              updatedAt: '2026-01-15T10:00:00.000Z'
      required:
        - categories
      title: Group categories response
      description: Active company categories ordered by name then ID.
      example:
        categories:
          - id: 11111111-1111-4111-8111-111111111111
            name: Teams
            description: Organizational teams.
            icon:
              emoji: 👥
              color: '#3B82F6'
            groupCount: 1
            employeeCount: 1
            createdByEmployeeId: employee-avery
            createdAt: '2026-01-15T10:00:00.000Z'
            updatedAt: '2026-01-15T10:00:00.000Z'
    EmployeeGroupCategory:
      type: object
      properties:
        id:
          type: string
          description: UUID of this company-wide group category.
          title: Category ID
          example: 11111111-1111-4111-8111-111111111111
        name:
          type: string
          description: Company-wide category display name.
          title: Category name
          example: Teams
        description:
          type:
            - string
            - 'null'
          description: Category description, or null when no description is saved.
          title: Description
          example: Organizational teams.
        icon:
          $ref: '#/components/schemas/EmployeeGroupCategoryIcon'
        groupCount:
          type: number
          description: Number of active groups in this category that the caller can read.
          title: Readable groups
          example: 1
        employeeCount:
          type: number
          description: >-
            Number of distinct non-archived employees in the group or accessible
            category groups.
          title: Employee count
          example: 1
        createdByEmployeeId:
          type:
            - string
            - 'null'
          description: >-
            Employee who created this resource, or null when no employee creator
            is recorded.
          title: Creator employee ID
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp in ISO 8601 format.
          title: Created at
          example: '2026-01-15T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Last recorded update timestamp in ISO 8601 format.
          title: Updated at
          example: '2026-01-15T10:00:00.000Z'
      required:
        - id
        - name
        - description
        - icon
        - groupCount
        - employeeCount
        - createdByEmployeeId
        - createdAt
        - updatedAt
      title: Group category
      description: >-
        Company-wide category with counts limited to groups readable by the
        caller.
      example:
        id: 11111111-1111-4111-8111-111111111111
        name: Teams
        description: Organizational teams.
        icon:
          emoji: 👥
          color: '#3B82F6'
        groupCount: 1
        employeeCount: 1
        createdByEmployeeId: employee-avery
        createdAt: '2026-01-15T10:00:00.000Z'
        updatedAt: '2026-01-15T10:00:00.000Z'
    EmployeeGroupCategoryIcon:
      anyOf:
        - type: object
          properties:
            emoji:
              type: string
              description: >-
                Emoji used for the category icon. Choose either the emoji or
                glyph form.
              title: Emoji
              example: 👥
            color:
              $ref: '#/components/schemas/EmployeeGroupCategoryColor'
          required:
            - emoji
            - color
          additionalProperties: false
        - type: object
          properties:
            glyph:
              type: string
              enum:
                - ACTIVITY
                - AI
                - ALERT
                - ALERT_TRIANGLE
                - ANALYTICS
                - ANONYMOUS
                - ANTENNA_BARS_1
                - ANTENNA_BARS_2
                - ANTENNA_BARS_3
                - ANTENNA_BARS_4
                - ANTENNA_BARS_5
                - ARROW_DOWN
                - ARROW_LEFT
                - ARROW_NARROW_UP_DASHED
                - ARROW_RIGHT
                - ARROW_TO_DOWN_LINE
                - ARROW_TO_UP_LINE
                - ARROW_UP
                - BELL_OFF
                - BELL_RING
                - BOT
                - BUILDING
                - CALENDAR
                - CALENDAR_PAUSE
                - CARD
                - CARET_UP_FILLED
                - CHANNEL
                - CHECK
                - CHECK_CIRCLE_FILLED
                - CHECKS
                - CHEVRON_DOWN
                - CHEVRON_DOWN_PIXEL
                - CHEVRON_RIGHT
                - CHOOSE_STATS
                - CLICK
                - CLOCK
                - CLOCK_FILLED
                - CODE
                - COG
                - COLUMNS
                - COMPANY
                - COMPARISON
                - COPY
                - COST
                - DATABASE
                - DEBUG
                - DEEP_DIVE
                - DELEGATED_ACCESS
                - DELIVERY
                - DEVICE_DESKTOP_ANALYTICS
                - DISCONNECT
                - DOCUMENT
                - DOCUMENT_TEMPLATE
                - DOT
                - EDIT
                - EMAIL
                - EMPLOYEE
                - EMPLOYEES
                - ERROR
                - EXTERNAL_LINK
                - EYE
                - FEATURE_INDETERMINATE
                - FEATURE_OFF
                - FEATURE_ON
                - FEATURES
                - FEEDBACK
                - FEEDBACK_GIVEN
                - FEEDBACK_RECEIVED
                - FILTER
                - FLAG
                - FLAME
                - FULL_SCREEN
                - GLOBE
                - GRID_DOTS
                - GROUPS
                - HAMBURGER
                - HAPPY
                - HEALTH
                - HELP_SQUARE_ROUNDED
                - HERO_NUMBER
                - HIGHLIGHTS
                - HOME
                - HOME_GRID
                - INBOX
                - IMPACT
                - INFO_CIRCLE
                - INTEGRATIONS
                - KEY
                - KNOWLEDGE
                - KEYBOARD_DOUBLE_ARROW_RIGHT
                - KEYBOARD_SINGLE_ARROW_RIGHT
                - LAYOUT_COLUMNS
                - LAYOUT_ROWS
                - LEADERBOARD
                - LIGHTNING_BOLT
                - LIST_SEARCH
                - LIGHT_BULB
                - LINK
                - LINKED_IN
                - LOADING
                - LOCK
                - LOGOUT
                - MAILBOX
                - MAPPING
                - MEETINGS
                - MEDAL
                - COMPANY_VALUES
                - MERGE
                - MEGAPHONE
                - MESSAGES
                - MICROPHONE
                - MOON
                - NEW_ACTIVITY
                - NEW_TAB
                - NOTES
                - NOTIFICATIONS
                - ONE_ON_ONE
                - ORG_CHART
                - ORGS
                - PAINT_BRUSH
                - PANEL_LEFT_CLOSE
                - PANEL_LEFT_OPEN
                - PANEL_RIGHT_CLOSE
                - PAUSE
                - PAUSE_FILLED
                - PAPER_CLIP
                - PENCIL_BOLT
                - PERFORMANCE
                - PLAY
                - PERSON
                - PERSON_CHECK
                - PERSON_MULTIPLE_CHECK
                - PIGGY_BANK
                - PIN
                - PIN_FILLED
                - PINNED_OFF
                - PLAY_CIRCLE
                - PLUS
                - PLUS_CIRCLE
                - PROGRESS_CHECK
                - PULSE
                - PUZZLED
                - RECAPS
                - RECEIPT_DOLLAR
                - RECORDING
                - RECORDING_NOT_FOUND
                - REFRESH
                - RELATIONSHIP_DIRECT_MANAGER
                - RELATIONSHIP_DIRECT_REPORT
                - RELATIONSHIP_PEER
                - RELATIONSHIP_SKIP_LEVEL_MANAGER
                - RELATIONSHIP_SKIP_LEVEL_REPORT
                - REPEAT
                - REPORT
                - REVIEWS
                - REVIEW_SELF
                - REVIEW_UPWARD
                - REVIEW_MANAGER
                - REVIEW_PEER
                - ROBOT_FACE
                - ROCKET
                - ROUTINES
                - SAD
                - SAVED_VIEW
                - SEARCH
                - SEND
                - SETTINGS
                - SHIELD
                - SHOUTOUT
                - SMILE_PLUS
                - SMS
                - SQUARE_ROUNDED_PLUS
                - SPINNER
                - SPINNER_LINE
                - STAR
                - STAR_FILLED
                - STATS
                - SUMMARY
                - SUN
                - SUPERPOWERS
                - SUPPORT
                - SURVEY
                - SWITCH
                - SYNC_INTEGRATION
                - TABLE
                - TAG
                - TEAM
                - TELESCOPE
                - TERMINAL
                - TEST
                - THREE_DOTS_VERTICAL
                - THUMBS_UP
                - TIME_SPENT
                - TRENDING_DOWN
                - TRENDING_UP
                - TRASH
                - TWITTER
                - USER
                - USER_CIRCLE
                - USER_PLUS
                - USERS_GROUP
                - WINDY
                - WINDY_CHAT
                - WINDY_CHAT_PLUS
                - WRENCH
                - X
                - X_CIRCLE_FILLED
                - YOUTUBE
              description: >-
                Supported standard icon identifier. Choose either the glyph or
                emoji form.
              title: Icon glyph
            color:
              $ref: '#/components/schemas/EmployeeGroupCategoryColor'
          required:
            - glyph
            - color
          additionalProperties: false
      title: Category icon
      description: >-
        Emoji/color or standard glyph/color object. The icon object rejects
        unknown fields.
      example:
        emoji: 👥
        color: '#3B82F6'
    EmployeeGroupCategoryColor:
      type: string
      description: >-
        Palette hex color, accepted case-insensitively: #3B82F6, #6366F1,
        #8B5CF6, #EC4899, #EF4444, #F97316, #F59E0B, #10B981, #14B8A6, #64748B.
      title: Icon color
      example: '#3B82F6'
  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.