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

# List users

> Returns a paginated list of users available to the authenticated API key



## OpenAPI

````yaml https://api.zapnito.com/api/docs/v1/swagger.json get /api/v1/users
openapi: 3.0.1
info:
  title: API V1
  version: v1
  description: Zapnito API Documentation
servers:
  - url: https://{host}
    description: Your community domain
    variables:
      host:
        default: your-community.com
        description: Your community domain, for example your-community.com
security: []
tags:
  - name: Health Check
    description: Check that the API is reachable and that your API key is valid
  - name: Identity
    description: Find out which community your API key belongs to
  - name: Users
    description: >-
      Look up the people in your community, update their profile and choose
      which notifications they receive
  - name: Organisations
    description: >-
      Create and update the organisations in your community and manage who
      belongs to them
  - name: Groups
    description: Create groups and manage which users belong to them
  - name: Invitations
    description: Invite people to join your community
  - name: Posts
    description: Create, read and update posts on behalf of your community members
  - name: Contents
    description: >-
      Read the published content of your community and publish, schedule or
      unpublish it
  - name: Channels
    description: List the channels in your community and the content published in each
  - name: Rooms
    description: Create and read the rooms where your community members meet
  - name: Tags
    description: Create tags and apply them to content
  - name: Badges
    description: Create badges and award them to content or to users
  - name: Custom Fields
    description: Read the custom profile fields your community asks its members to fill in
  - name: Third-Party Resources
    description: >-
      Link to resources hosted outside your community so they appear alongside
      your content
  - name: Rest Hooks
    description: >-
      Subscribe a URL to events in your community, so you are told when they
      happen
paths:
  /api/v1/users:
    get:
      tags:
        - Users
      summary: List users
      description: Returns a paginated list of users available to the authenticated API key
      operationId: listUsers
      parameters:
        - name: page
          in: query
          required: false
          description: 'Page number (default: 1)'
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: 'Number of items per page (default: 20)'
          schema:
            type: integer
        - name: query
          in: query
          required: false
          description: Search term used to filter results
          schema:
            type: string
      responses:
        '200':
          description: A page of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                required:
                  - users
        '401':
          description: >-
            The API key is missing or invalid. The response body is the text
            `HTTP Token: Access denied.`
      security:
        - tokenAuth: []
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Jane Doe
        email:
          type: string
          format: email
          example: jane@example.com
        title:
          type: string
          nullable: true
          example: Senior Engineer
        company:
          type: string
          nullable: true
          example: Acme Corp
        professional_reg_number:
          type: string
          nullable: true
          example: PRN-001
        country_code:
          type: string
          nullable: true
          example: GB
        unsubscribe_all:
          type: boolean
          example: false
          description: Whether the user receives no email from the community
        custom_field_option_ids:
          type: array
          items:
            type: integer
          example:
            - 1
            - 2
          description: The custom field options the user has chosen in this community
        groups:
          type: array
          description: The groups of the community the user belongs to
          items:
            type: object
            properties:
              id:
                type: integer
                example: 10
              uuid:
                type: string
                example: abc-123
              name:
                type: string
                example: Admins
            required:
              - id
              - uuid
              - name
        sso_uids:
          type: array
          description: The identifiers the user has with single sign-on providers
          items:
            type: object
            properties:
              sso_provider:
                type: string
                example: saml
              sso_uid:
                type: string
                example: user-uid-001
            required:
              - sso_provider
              - sso_uid
        avatar_url:
          type: string
          nullable: true
          example: https://example.com/avatar.jpg
        url:
          type: string
          example: https://example.com/users/jane-doe
          description: The address of the profile of the user
      required:
        - id
        - name
        - email
        - unsubscribe_all
        - custom_field_option_ids
        - groups
        - sso_uids
  securitySchemes:
    tokenAuth:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        API authentication using your community API secret. The value below is
        sent as the Authorization header verbatim, so paste the whole header
        value including the prefix: Token token=<api-key>
      x-default: Token token=<api-key>

````

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