WordPress Users API

openapi: 3.0.3
info:
  title: WordPress REST Block Types Users API
  description: The WordPress REST API provides endpoints for WordPress data types that allow developers to interact with sites remotely by sending and receiving JSON objects. It is the backbone of the WordPress Block Editor and enables headless CMS, mobile apps, and third-party integrations.
  version: v2
  contact:
    name: WordPress Developer Resources
    url: https://developer.wordpress.org/rest-api/
  license:
    name: GPL-2.0-or-later
    url: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  x-generated-from: documentation
servers:
- url: https://{site}/wp-json
  description: WordPress site REST API root
  variables:
    site:
      default: example.com
      description: Your WordPress site hostname
security:
- cookieAuth: []
- basicAuth: []
- applicationPassword: []
tags:
- name: Users
  description: Manage WordPress users
paths:
  /wp/v2/users:
    get:
      operationId: listUsers
      summary: WordPress List Users
      description: Retrieves a collection of users. Requires authentication for most contexts.
      tags:
      - Users
      parameters:
      - name: page
        in: query
        description: Current page of the collection.
        schema:
          type: integer
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Maximum number of items to be returned.
        schema:
          type: integer
          default: 10
        example: 10
      - name: roles
        in: query
        description: Limit result set to users matching at least one specific role.
        schema:
          type: array
          items:
            type: string
        example:
        - administrator
        - editor
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                ListUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    name: admin
                    slug: admin
                    avatar_urls:
                      '96': https://secure.gravatar.com/avatar/abc123?s=96
                    roles:
                    - administrator
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /wp/v2/users/{id}:
    get:
      operationId: getUser
      summary: WordPress Get User
      description: Retrieves a single user by ID.
      tags:
      - Users
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the user.
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                GetUser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    name: admin
                    slug: admin
                    roles:
                    - administrator
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    User:
      type: object
      description: A WordPress user object
      properties:
        id:
          type: integer
          description: Unique identifier for the user
          example: 1
        name:
          type: string
          description: Display name for the user
          example: admin
        slug:
          type: string
          description: An alphanumeric identifier for the user
          example: admin
        description:
          type: string
          description: Description of the user
          example: Site administrator
        link:
          type: string
          description: URL of the user
          example: https://example.com/author/admin/
        avatar_urls:
          type: object
          description: Avatar URLs for the user keyed by image size
          additionalProperties:
            type: string
          example:
            '96': https://secure.gravatar.com/avatar/abc123?s=96
        roles:
          type: array
          description: Roles assigned to the user
          items:
            type: string
          example:
          - administrator
    ErrorResponse:
      type: object
      description: A WordPress REST API error response
      properties:
        code:
          type: string
          description: Error code
          example: rest_forbidden
        message:
          type: string
          description: Human-readable error message
          example: Sorry, you are not allowed to do that.
        data:
          type: object
          description: Additional data about the error
          properties:
            status:
              type: integer
              description: HTTP status code
              example: 403
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFound404Example:
              summary: Not found example
              x-microcks-default: true
              value:
                code: rest_post_invalid_id
                message: Invalid post ID.
                data:
                  status: 404
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Unauthorized401Example:
              summary: Unauthorized example
              x-microcks-default: true
              value:
                code: rest_not_logged_in
                message: You are not currently logged in.
                data:
                  status: 401
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: wordpress_logged_in
      description: WordPress cookie authentication with nonce (X-WP-Nonce header required)
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Application Passwords (WordPress 5.6+)
    applicationPassword:
      type: http
      scheme: basic
      description: Application Passwords - generate per-application passwords from user profile in WordPress admin