Automattic Themes API

openapi: 3.2.0
info:
  title: Automattic Themes API
  x-derived-by: API Evangelist enrichment pipeline
  x-refined-note:
  - x-derived-from differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged themes across 3 of this provider''s published API definitions: automattic-wordpress-com-rest-v1-1-openapi.yml, automattic-wordpress-com-wp-v2-openapi.yml, automattic-wordpress-com-wpcom-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public-api.wordpress.com/rest/v1.1
- url: https://public-api.wordpress.com
security:
- bearerAuth: []
tags:
- name: themes
paths:
  /sites/{site}/themes:
    get:
      operationId: getSitesBySiteThemes
      summary: Get information about a theme on WordPress.com.
      description: Get information about a theme on WordPress.com.
      tags:
      - themes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  themes:
                    type: array
                    items: {}
                    description: A list of themes.
                  count:
                    type: integer
                    description: The amount of themes.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain.
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      - name: locale
        in: query
        required: false
        schema:
          type: string
        description: 'ISO 639-1 Locale. Default: en.'
      - name: currency
        in: query
        required: false
        schema:
          type: string
        description: 'Currency. Default: USD.'
      - name: extended
        in: query
        required: false
        schema:
          type: boolean
        description: 'To add additional information. Default: False.'
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/themes/mine:
    get:
      operationId: getSitesBySiteThemesMine
      summary: Get the active theme of a site.
      description: Get the active theme of a site.
      tags:
      - themes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The theme's ID..
                  screenshot:
                    type: string
                    description: A theme screenshot URL
                  name:
                    type: string
                    description: The name of the theme.
                  theme_uri:
                    type: string
                    description: The URI of the theme's webpage.
                  description:
                    type: string
                    description: A description of the theme.
                  tags:
                    type: array
                    items: {}
                    description: Tags indicating styles and features of the theme.
                  price:
                    type: number
                    description: The price, in USD, of the theme.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
    post:
      operationId: postSitesBySiteThemesMine
      summary: Change the active theme of a site.
      description: Change the active theme of a site.
      tags:
      - themes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The theme's ID.
                  screenshot:
                    type: string
                    description: A theme screenshot URL
                  name:
                    type: string
                    description: The name of the theme.
                  description:
                    type: string
                    description: A description of the theme.
                  tags:
                    type: array
                    items: {}
                    description: Tags indicating styles and features of the theme.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                theme:
                  type: string
                  description: The ID of the theme that should be activated
                style_variation_slug:
                  type: string
                  description: Optional. The slug of the style variation to apply to the theme.
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /themes:
    get:
      operationId: getThemes
      summary: Get a list of all available themes on WordPress.com.
      description: Get a list of all available themes on WordPress.com.
      tags:
      - themes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  themes:
                    type: array
                    items: {}
                    description: A list of themes.
                  count:
                    type: integer
                    description: The amount of themes.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      - name: locale
        in: query
        required: false
        schema:
          type: string
        description: 'ISO 639-1 Locale. Default: en.'
      - name: currency
        in: query
        required: false
        schema:
          type: string
        description: 'Currency. Default: USD'
      - name: retired
        in: query
        required: false
        schema:
          type: boolean
        description: 'Include retired themes? Default: false.'
      - name: extended
        in: query
        required: false
        schema:
          type: boolean
        description: 'To add additional information. Default: False.'
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /themes/{theme_slug}:
    get:
      operationId: getThemesByThemeSlug
      summary: Get a theme on WordPress.com.
      description: Get a theme on WordPress.com.
      tags:
      - themes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The theme's ID. Usually identical to its slug.
                  slug:
                    type: string
                    description: The theme's slug.
                  name:
                    type: string
                    description: The name of the theme.
                  author:
                    type: string
                    description: The name of the author.
                  author_uri:
                    type: string
                    format: uri
                    description: The URL to the author's homepage.
                  theme_uri:
                    type: string
                    format: uri
                    description: The URL to the theme's homepage.
                  demo_uri:
                    type: string
                    format: uri
                    description: The URL to the demo page on WordPress.com.
                  version:
                    type: string
                    description: The version of the theme.
                  template:
                    type: string
                    description: The template name of the parent theme. Empty string if there is no parent.
                  screenshot:
                    type: string
                    format: uri
                    description: A theme screenshot URL. Equal to the first screenshot in the screenshots array.
                  screenshots:
                    type: array
                    items: {}
                    description: Screenshot URLs.
                  description:
                    type: string
                    description: A description of the theme.
                  description_long:
                    type: string
                    description: A detailed version of the theme's description
                  date_launched:
                    type: string
                    format: date-time
                    description: Date when the theme was launched on WordPress.com.
                  date_updated:
                    type: string
                    format: date-time
                    description: Date when the theme was last updated.
                  price:
                    type: string
                    description: 'value: (float) The price of the theme in the specified currency.; currency: (string=USD) The currency of the theme price.; display: (string) A representation of the theme price, ready to be displayed.'
                    enum:
                    - value
                    - currency
                    - display
                  language:
                    type: string
                    description: 'The language of the theme information retrieved. Default: ''en''.'
                  taxonomies:
                    type: array
                    items: {}
                    description: A multidimensional array of term objects, associated with the theme.
                  download_uri:
                    type: string
                    format: uri
                    description: Download URL.
                  rank_popularity:
                    type: integer
                    description: The theme's popularity rank.
                  rank_trending:
                    type: integer
                    description: The theme's trending rank.
                  extended:
                    type: object
                    description: Additional information, such as license, long description, or support documentation.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: theme_slug
        in: path
        required: true
        schema:
          type: string
        description: The slug of the theme.
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      - name: locale
        in: query
        required: false
        schema:
          type: string
        description: 'ISO 639-1 Locale. Default: en.'
      - name: currency
        in: query
        required: false
        schema:
          type: string
        description: 'Currency. Default: USD'
      - name: retired
        in: query
        required: false
        schema:
          type: boolean
        description: 'Include retired themes? Default: false.'
      - name: extended
        in: query
        required: false
        schema:
          type: boolean
        description: 'To add additional information. Default: False.'
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /wp/v2/sites/{wpcom_site}/themes:
    get:
      operationId: getWpV2SitesbyWpcomSiteThemes
      summary: GET /wp/v2/sites/{wpcom_site}/themes
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: wpcom_site
        in: path
        required: true
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Limit result set to themes assigned one or more statuses.
    servers:
    - url: https://public-api.wordpress.com
  /wp/v2/sites/{wpcom_site}/themes/{stylesheet}:
    get:
      operationId: getWpV2SitesbyWpcomSiteThemesbyStylesheet
      summary: GET /wp/v2/sites/{wpcom_site}/themes/{stylesheet}
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: wpcom_site
        in: path
        required: true
        schema:
          type: string
      - name: stylesheet
        in: path
        required: true
        schema:
          type: string
    servers:
    - url: https://public-api.wordpress.com
  /wpcom/v2/sites/{wpcom_site}/themes/activation-history:
    get:
      operationId: getWpcomV2SitesbyWpcomSiteThemesActivationHistory
      summary: GET /wpcom/v2/sites/{wpcom_site}/themes/activation-history
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: wpcom_site
        in: path
        required: true
        schema:
          type: string
    servers:
    - url: https://public-api.wordpress.com
  /wpcom/v2/themes:
    get:
      operationId: getWpcomV2Themes
      summary: GET /wpcom/v2/themes
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: search
        in: query
        required: false
        schema:
          type: string
    servers:
    - url: https://public-api.wordpress.com
  /wpcom/v2/themes/readymade-templates:
    get:
      operationId: getWpcomV2ThemesReadymadeTemplates
      summary: GET /wpcom/v2/themes/readymade-templates
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
    servers:
    - url: https://public-api.wordpress.com
  /wpcom/v2/themes/readymade-templates/{template_id}:
    get:
      operationId: getWpcomV2ThemesReadymadeTemplatesbyTemplateId
      summary: GET /wpcom/v2/themes/readymade-templates/{template_id}
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
    servers:
    - url: https://public-api.wordpress.com
  /wpcom/v2/themes/{theme}/premium-details:
    get:
      operationId: getWpcomV2ThemesbyThemePremiumDetails
      summary: GET /wpcom/v2/themes/{theme}/premium-details
      tags:
      - themes
      responses:
        '200':
          description: OK
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPRestError'
      parameters:
      - name: theme
        in: path
        required: true
        schema:
          type: string
    servers:
    - url: https://public-api.wordpress.com
components:
  schemas:
    Error:
      type: object
      description: WordPress.com REST API error envelope (observed live).
      properties:
        error:
          type: string
          examples:
          - not_found
        message:
          type: string
    WPRestError:
      type: object
      description: WordPress REST API error envelope (observed on public-api.wordpress.com).
      properties:
        code:
          type: string
          example: rest_unauthorized
        message:
          type: string
          example: Authentication required.
        data:
          type: object
          properties:
            status:
              type: integer
              example: 401
  securitySchemes:
    oauth2:
      type: oauth2
      description: WordPress.com OAuth 2.1 (see /.well-known/openid-configuration).
      flows:
        authorizationCode:
          authorizationUrl: https://public-api.wordpress.com/oauth2-1/authorize
          tokenUrl: https://public-api.wordpress.com/oauth2-1/token
          refreshUrl: https://public-api.wordpress.com/oauth2-1/token
          scopes:
            global: ''
            auth: ''
            openid: ''
            profile: ''
            email: ''
            users: ''
            sites: ''
            posts: ''
            comments: ''
            taxonomy: ''
            follow: ''
            sharing: ''
            freshly-pressed: ''
            notifications: ''
            insights: ''
            read: ''
            stats: ''
            media: ''
            menus: ''
            batch: ''
            videos: ''
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <access_token>'
x-refined-from:
- automattic-wordpress-com-rest-v1-1-openapi.yml
- automattic-wordpress-com-wp-v2-openapi.yml
- automattic-wordpress-com-wpcom-v2-openapi.yml