WordPress REST API

openapi: 3.0.3
info:
  title: WordPress REST 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: Posts
    description: Manage WordPress posts
  - name: Pages
    description: Manage WordPress pages
  - name: Media
    description: Manage WordPress media library
  - name: Comments
    description: Manage WordPress comments
  - name: Users
    description: Manage WordPress users
  - name: Categories
    description: Manage post categories
  - name: Tags
    description: Manage post tags
  - name: Taxonomies
    description: Manage WordPress taxonomies
  - name: Blocks
    description: Manage reusable blocks
  - name: Block Types
    description: Query registered block types
  - name: Themes
    description: Manage WordPress themes
  - name: Plugins
    description: Manage WordPress plugins
  - name: Settings
    description: Manage site settings
  - name: Search
    description: Search across WordPress content
  - name: Post Types
    description: Query registered post types

paths:
  /wp/v2/posts:
    get:
      operationId: listPosts
      summary: WordPress List Posts
      description: Retrieves a collection of posts from the WordPress site. Supports filtering, ordering, and pagination.
      tags:
        - Posts
      parameters:
        - name: context
          in: query
          description: Scope under which the request is made; determines fields present in response.
          schema:
            type: string
            enum: [view, embed, edit]
            default: view
          example: view
        - 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 in result set.
          schema:
            type: integer
            default: 10
            maximum: 100
          example: 10
        - name: search
          in: query
          description: Limit results to those matching a string.
          schema:
            type: string
          example: WordPress tutorial
        - name: status
          in: query
          description: Limit result set to posts assigned one or more statuses.
          schema:
            type: string
            default: publish
          example: publish
        - name: author
          in: query
          description: Limit result set to posts assigned to specific authors.
          schema:
            type: array
            items:
              type: integer
          example: [1]
        - name: categories
          in: query
          description: Limit result set to items with specific terms assigned in the categories taxonomy.
          schema:
            type: array
            items:
              type: integer
          example: [5]
        - name: tags
          in: query
          description: Limit result set to items with specific terms assigned in the tags taxonomy.
          schema:
            type: array
            items:
              type: integer
          example: [12]
        - name: orderby
          in: query
          description: Sort collection by object attribute.
          schema:
            type: string
            enum: [author, date, id, include, modified, parent, relevance, slug, include_slugs, title]
            default: date
          example: date
        - name: order
          in: query
          description: Order sort attribute ascending or descending.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
      responses:
        '200':
          description: A list of posts
          headers:
            X-WP-Total:
              description: Total number of items in the collection
              schema:
                type: integer
            X-WP-TotalPages:
              description: Total number of pages available
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
              examples:
                ListPosts200Example:
                  summary: Default listPosts 200 response
                  x-microcks-default: true
                  value:
                    - id: 123
                      date: '2026-04-15T10:30:00'
                      date_gmt: '2026-04-15T10:30:00'
                      status: publish
                      type: post
                      link: https://example.com/2026/04/my-first-post/
                      title:
                        rendered: My First WordPress Post
                      content:
                        rendered: '<p>Welcome to my WordPress site.</p>'
                        protected: false
                      excerpt:
                        rendered: '<p>Welcome to my WordPress site.</p>'
                        protected: false
                      author: 1
                      featured_media: 0
                      comment_status: open
                      ping_status: open
                      sticky: false
                      template: ''
                      format: standard
                      categories: [1]
                      tags: []
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPost
      summary: WordPress Create Post
      description: Creates a new post on the WordPress site. Requires authentication with appropriate user capabilities.
      tags:
        - Posts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInput'
            examples:
              CreatePostRequestExample:
                summary: Default createPost request
                x-microcks-default: true
                value:
                  title: My New Post
                  content: This is the post content.
                  status: publish
                  categories: [1]
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                CreatePost201Example:
                  summary: Default createPost 201 response
                  x-microcks-default: true
                  value:
                    id: 124
                    date: '2026-05-03T12:00:00'
                    status: publish
                    type: post
                    title:
                      rendered: My New Post
                    content:
                      rendered: '<p>This is the post content.</p>'
                      protected: false
                    author: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/posts/{id}:
    get:
      operationId: getPost
      summary: WordPress Get Post
      description: Retrieves a single post by ID from the WordPress site.
      tags:
        - Posts
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier for the post.
          schema:
            type: integer
          example: 123
        - name: context
          in: query
          description: Scope under which the request is made.
          schema:
            type: string
            enum: [view, embed, edit]
            default: view
          example: view
      responses:
        '200':
          description: A single post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                GetPost200Example:
                  summary: Default getPost 200 response
                  x-microcks-default: true
                  value:
                    id: 123
                    date: '2026-04-15T10:30:00'
                    status: publish
                    type: post
                    link: https://example.com/2026/04/my-first-post/
                    title:
                      rendered: My First WordPress Post
                    content:
                      rendered: '<p>Welcome to my WordPress site.</p>'
                      protected: false
                    author: 1
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updatePost
      summary: WordPress Update Post
      description: Updates an existing post by ID. Requires authentication.
      tags:
        - Posts
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier for the post.
          schema:
            type: integer
          example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInput'
      responses:
        '200':
          description: Post updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                UpdatePost200Example:
                  summary: Default updatePost 200 response
                  x-microcks-default: true
                  value:
                    id: 123
                    status: publish
                    title:
                      rendered: My Updated Post
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deletePost
      summary: WordPress Delete Post
      description: Deletes a post by ID. Requires authentication with appropriate user capabilities.
      tags:
        - Posts
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier for the post.
          schema:
            type: integer
          example: 123
        - name: force
          in: query
          description: Whether to bypass trash and force deletion.
          schema:
            type: boolean
            default: false
          example: false
      responses:
        '200':
          description: Post deleted (moved to trash or permanently deleted)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
              examples:
                DeletePost200Example:
                  summary: Default deletePost 200 response
                  x-microcks-default: true
                  value:
                    id: 123
                    status: trash
                    title:
                      rendered: My First WordPress Post
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/pages:
    get:
      operationId: listPages
      summary: WordPress List Pages
      description: Retrieves a collection of pages from the WordPress site.
      tags:
        - Pages
      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: status
          in: query
          description: Limit result set to pages with a specific status.
          schema:
            type: string
            default: publish
          example: publish
        - name: parent
          in: query
          description: Limit result set to pages with a specific parent ID.
          schema:
            type: integer
          example: 0
      responses:
        '200':
          description: A list of pages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
              examples:
                ListPages200Example:
                  summary: Default listPages 200 response
                  x-microcks-default: true
                  value:
                    - id: 2
                      date: '2026-01-01T00:00:00'
                      status: publish
                      type: page
                      title:
                        rendered: About
                      content:
                        rendered: '<p>About this site.</p>'
                        protected: false
                      parent: 0
                      menu_order: 0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPage
      summary: WordPress Create Page
      description: Creates a new page. Requires authentication.
      tags:
        - Pages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageInput'
      responses:
        '201':
          description: Page created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
              examples:
                CreatePage201Example:
                  summary: Default createPage 201 response
                  x-microcks-default: true
                  value:
                    id: 10
                    status: publish
                    title:
                      rendered: New Page
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/pages/{id}:
    get:
      operationId: getPage
      summary: WordPress Get Page
      description: Retrieves a single page by ID.
      tags:
        - Pages
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier for the page.
          schema:
            type: integer
          example: 2
      responses:
        '200':
          description: A single page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
              examples:
                GetPage200Example:
                  summary: Default getPage 200 response
                  x-microcks-default: true
                  value:
                    id: 2
                    status: publish
                    title:
                      rendered: About
                    content:
                      rendered: '<p>About this site.</p>'
                      protected: false
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/media:
    get:
      operationId: listMedia
      summary: WordPress List Media
      description: Retrieves a collection of media items from the media library.
      tags:
        - Media
      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: media_type
          in: query
          description: Limit result set to attachments of a particular media type.
          schema:
            type: string
            enum: [image, video, text, application, audio]
          example: image
        - name: mime_type
          in: query
          description: Limit result set to attachments of a specific MIME type.
          schema:
            type: string
          example: image/jpeg
      responses:
        '200':
          description: A list of media items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MediaItem'
              examples:
                ListMedia200Example:
                  summary: Default listMedia 200 response
                  x-microcks-default: true
                  value:
                    - id: 45
                      date: '2026-03-10T09:00:00'
                      status: inherit
                      type: attachment
                      mime_type: image/jpeg
                      source_url: https://example.com/wp-content/uploads/2026/03/photo.jpg
                      title:
                        rendered: photo
                      alt_text: A sample photo
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/media/{id}:
    get:
      operationId: getMedia
      summary: WordPress Get Media Item
      description: Retrieves a single media item by ID.
      tags:
        - Media
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier for the media item.
          schema:
            type: integer
          example: 45
      responses:
        '200':
          description: A single media item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaItem'
              examples:
                GetMedia200Example:
                  summary: Default getMedia 200 response
                  x-microcks-default: true
                  value:
                    id: 45
                    status: inherit
                    mime_type: image/jpeg
                    source_url: https://example.com/wp-content/uploads/2026/03/photo.jpg
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/comments:
    get:
      operationId: listComments
      summary: WordPress List Comments
      description: Retrieves a collection of comments. Public endpoint returns approved comments.
      tags:
        - Comments
      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: post
          in: query
          description: Limit result set to comments assigned to specific post IDs.
          schema:
            type: array
            items:
              type: integer
          example: [123]
        - name: status
          in: query
          description: Limit result set to comments assigned a specific status.
          schema:
            type: string
            default: approve
          example: approve
      responses:
        '200':
          description: A list of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              examples:
                ListComments200Example:
                  summary: Default listComments 200 response
                  x-microcks-default: true
                  value:
                    - id: 1
                      post: 123
                      parent: 0
                      author: 0
                      author_name: John Doe
                      author_email: [email protected]
                      date: '2026-04-16T08:00:00'
                      content:
                        rendered: '<p>Great post!</p>'
                      status: approved
                      type: comment
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createComment
      summary: WordPress Create Comment
      description: Creates a new comment on a post.
      tags:
        - Comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentInput'
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              examples:
                CreateComment201Example:
                  summary: Default createComment 201 response
                  x-microcks-default: true
                  value:
                    id: 2
                    post: 123
                    status: approved
                    author_name: Jane Smith
                    content:
                      rendered: '<p>Thanks for sharing!</p>'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /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

  /wp/v2/categories:
    get:
      operationId: listCategories
      summary: WordPress List Categories
      description: Retrieves a collection of post categories.
      tags:
        - Categories
      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.
          schema:
            type: integer
            default: 10
          example: 10
        - name: search
          in: query
          description: Limit results to matching categories.
          schema:
            type: string
          example: technology
        - name: hide_empty
          in: query
          description: Whether to hide terms not assigned to any posts.
          schema:
            type: boolean
            default: false
          example: false
      responses:
        '200':
          description: A list of categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Term'
              examples:
                ListCategories200Example:
                  summary: Default listCategories 200 response
                  x-microcks-default: true
                  value:
                    - id: 1
                      count: 12
                      description: ''
                      link: https://example.com/category/uncategorized/
                      name: Uncategorized
                      slug: uncategorized
                      taxonomy: category
                      parent: 0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCategory
      summary: WordPress Create Category
      description: Creates a new category. Requires authentication.
      tags:
        - Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TermInput'
      responses:
        '201':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Term'
              examples:
                CreateCategory201Example:
                  summary: Default createCategory 201 response
                  x-microcks-default: true
                  value:
                    id: 5
                    name: Technology
                    slug: technology
                    taxonomy: category
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/tags:
    get:
      operationId: listTags
      summary: WordPress List Tags
      description: Retrieves a collection of post tags.
      tags:
        - Tags
      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.
          schema:
            type: integer
            default: 10
          example: 10
        - name: search
          in: query
          description: Limit results to matching tags.
          schema:
            type: string
          example: api
        - name: hide_empty
          in: query
          description: Whether to hide terms not assigned to any posts.
          schema:
            type: boolean
            default: false
          example: false
      responses:
        '200':
          description: A list of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Term'
              examples:
                ListTags200Example:
                  summary: Default listTags 200 response
                  x-microcks-default: true
                  value:
                    - id: 12
                      count: 5
                      description: ''
                      link: https://example.com/tag/api/
                      name: API
                      slug: api
                      taxonomy: post_tag
                      parent: 0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/search:
    get:
      operationId: searchContent
      summary: WordPress Search Content
      description: Searches across WordPress content types including posts, pages, and other objects.
      tags:
        - Search
      parameters:
        - name: search
          in: query
          required: true
          description: Limit results to those matching a string.
          schema:
            type: string
          example: WordPress API
        - name: type
          in: query
          description: Limit results to items of an object type.
          schema:
            type: string
            enum: [post, term, post-format]
            default: post
          example: post
        - name: subtype
          in: query
          description: Limit results to items of one or more object subtypes.
          schema:
            type: string
          example: post
        - 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 return.
          schema:
            type: integer
            default: 10
          example: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
              examples:
                SearchContent200Example:
                  summary: Default searchContent 200 response
                  x-microcks-default: true
                  value:
                    - id: 123
                      title: My First WordPress Post
                      url: https://example.com/2026/04/my-first-post/
                      type: post
                      subtype: post
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /wp/v2/settings:
    get:
      operationId: getSettings
      summary: WordPress Get Settings
      description: Retrieves registered site settings. Requires authentication.
      tags:
        - Settings
      responses:
        '200':
          description: Site settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settings'
              examples:
                GetSettings200Example:
                  summary: Default getSettings 200 response
                  x-microcks-default: true
                  value:
                    title: My WordPress Site
                    description: Just another WordPress site
                    url: https://example.com
                    email: [email protected]
                    timezone: America/New_York
                    date_format: F j, Y
                    time_format: g:i a
                    start_of_wee

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordpress/refs/heads/main/openapi/wordpress-rest-api-openapi.yml