Automattic Media API

openapi: 3.2.0
info:
  title: Automattic Media 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 media across 4 of this provider''s published API definitions: automattic-wordpress-com-rest-v1-1-openapi.yml, automattic-wordpress-com-rest-v1-2-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/rest/v1.2
- url: https://public-api.wordpress.com
security:
- bearerAuth: []
tags:
- name: media
paths:
  /sites/{site}/media/:
    get:
      operationId: getSitesBySiteMedia
      summary: Get a list of items in the media library.
      description: Get a list of items in the media library.
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  media:
                    type: array
                    items: {}
                    description: Array of media objects
                  found:
                    type: integer
                    description: The number of total results found
                  meta:
                    type: object
                    description: Meta data
        '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: number
        in: query
        required: false
        schema:
          type: integer
        description: 'The number of media items to return. Limit: 100. Default: 20.'
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: 0-indexed offset.
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Return the Nth 1-indexed page of posts. Takes precedence over the offset parameter.
      - name: page_handle
        in: query
        required: false
        schema:
          type: string
        description: A page handle, returned from a previous API call as a meta.next_page property. This is the most efficient way to fetch the next page of results.
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
        description: 'DESC: (default) Return files in descending order. For dates, that means newest to oldest.; ASC: Return files in ascending order. For dates, that means oldest to newest.'
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - date
          - title
          - ID
        description: 'date: (default) Order by the uploaded time of each file.; title: Order lexicographically by file titles.; ID: Order by media ID.'
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Search query.
      - name: post_ID
        in: query
        required: false
        schema:
          type: integer
        description: Default is showing all items. The post where the media item is attached. 0 shows unattached media items.
      - name: mime_type
        in: query
        required: false
        schema:
          type: string
        description: Default is empty. Filter by mime type (e.g., 'image/jpeg', 'application/pdf'). Partial searches also work (e.g. passing 'image' will search for all image files).
      - name: after
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Return media items uploaded after the specified datetime.
      - name: before
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Return media items uploaded before the specified datetime.
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/media/new:
    post:
      operationId: postSitesBySiteMediaNew
      summary: Upload a new piece of media.
      description: Upload a new piece of media.
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  media:
                    type: array
                    items: {}
                    description: Array of uploaded media objects
                  errors:
                    type: array
                    items: {}
                    description: Array of error messages of uploading media failures
        '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.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                media:
                  type: string
                  description: 'An array of media to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See allowed_file_types in the options response of the site endpoint.Example:curl \--form ''media[]=@/path/to/file.jpg'' \-H ''Authorization: BEARER your-token'' \''https://public-api.wordpress.com/rest/v1/sites/123/media/new'''
                media_urls:
                  type: array
                  items: {}
                  description: An array of URLs to upload to the post. Errors produced by media uploads, if any, will be in `media_errors` in the response.
                attrs:
                  type: array
                  items: {}
                  description: 'An array of attributes (`title`, `description`, `caption` `alt` for images, `artist` for audio, `album` for audio, and `parent_id`) are supported to assign to the media uploaded via the `media` or `media_urls` properties. You must use a numeric index for the keys of `attrs` which follows the same sequence as `media` and `media_urls`. Example:curl \--form ''media[]=@/path/to/file1.jpg'' \--form ''media_urls[]=http://example.com/file2.jpg'' \ \--form ''attrs[0][caption]=This will be the caption for file1.jpg'' \--form ''attrs[1][title]=This will be the title for file2.jpg'' \-H ''Authorization: BEARER your-token'' \''https://public-api.wordpress.com/rest/v1/sites/123/media/new'''
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/media/{media_ID}:
    get:
      operationId: getSitesBySiteMediaByMediaId
      summary: Get a single media item (by ID).
      description: Get a single media item (by ID).
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The ID of the media item
                  date:
                    type: string
                    format: date-time
                    description: The date the media was uploaded
                  post_ID:
                    type: integer
                    description: ID of the post this media is attached to
                  author_ID:
                    type: integer
                    description: ID of the user who uploaded the media
                  URL:
                    type: string
                    description: URL to the file
                  guid:
                    type: string
                    description: Unique identifier
                  file:
                    type: string
                    description: Filename
                  extension:
                    type: string
                    description: File extension
                  mime_type:
                    type: string
                    description: File MIME type
                  title:
                    type: string
                    description: Filename
                  caption:
                    type: string
                    description: User-provided caption of the file
                  description:
                    type: string
                    description: Description of the file
                  alt:
                    type: string
                    description: Alternative text for image files.
                  thumbnails:
                    type: object
                    description: Media item thumbnail URL options
                  height:
                    type: integer
                    description: (Image & video only) Height of the media item
                  width:
                    type: integer
                    description: (Image & video only) Width of the media item
                  length:
                    type: integer
                    description: (Video & audio only) Duration of the media item, in seconds
                  exif:
                    type: array
                    items: {}
                    description: (Image & audio only) Exif (meta) information about the media item
                  rating:
                    type: string
                    description: (Video only) VideoPress rating of the video
                  display_embed:
                    type: string
                    description: Video only. Whether to share or not the video.
                  allow_download:
                    type: string
                    description: Video only. Whether the video can be downloaded or not.
                  videopress_guid:
                    type: string
                    description: (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress
                  videopress_processing_done:
                    type: boolean
                    description: (Video only) If the video is uploaded on a blog with VideoPress, this will return the status of processing on the video.
        '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: media_ID
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the media item
      - 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: postSitesBySiteMediaByMediaId
      summary: Edit basic information about a media item.
      description: Edit basic information about a media item.
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The ID of the media item
                  date:
                    type: string
                    format: date-time
                    description: The date the media was uploaded
                  post_ID:
                    type: integer
                    description: ID of the post this media is attached to
                  author_ID:
                    type: integer
                    description: ID of the user who uploaded the media
                  URL:
                    type: string
                    description: URL to the file
                  guid:
                    type: string
                    description: Unique identifier
                  file:
                    type: string
                    description: File name
                  extension:
                    type: string
                    description: File extension
                  mime_type:
                    type: string
                    description: File mime type
                  title:
                    type: string
                    description: File name
                  caption:
                    type: string
                    description: User provided caption of the file
                  description:
                    type: string
                    description: Description of the file
                  alt:
                    type: string
                    description: Alternative text for image files.
                  thumbnails:
                    type: object
                    description: Media item thumbnail URL options
                  height:
                    type: integer
                    description: (Image & video only) Height of the media item
                  width:
                    type: integer
                    description: (Image & video only) Width of the media item
                  length:
                    type: integer
                    description: (Video & audio only) Duration of the media item, in seconds
                  exif:
                    type: array
                    items: {}
                    description: (Image & audio only) Exif (meta) information about the media item
                  rating:
                    type: string
                    description: (Video only) VideoPress rating of the video
                  display_embed:
                    type: string
                    description: Video only. Whether to share or not the video.
                  allow_download:
                    type: string
                    description: Video only. Whether the video can be downloaded or not.
                  privacy_setting:
                    type: integer
                    description: Video only. The privacy level for the video.
                  videopress_guid:
                    type: string
                    description: (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress
                  videopress_processing_done:
                    type: boolean
                    description: (Video only) If the video is uploaded on a blog with VideoPress, this will return the status of processing on the video.
        '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: media_ID
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the media item
      - 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.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_id:
                  type: integer
                  description: ID of the post this media is attached to
                title:
                  type: string
                  description: The file name.
                caption:
                  type: string
                  description: File caption.
                description:
                  type: string
                  description: Description of the file.
                alt:
                  type: string
                  description: Alternative text for image files.
                rating:
                  type: string
                  description: Video only. Video rating.
                display_embed:
                  type: string
                  description: Video only. Whether to share or not the video.
                allow_download:
                  type: string
                  description: Video only. Whether the video can be downloaded or not.
                privacy_setting:
                  type: integer
                  description: Video only. The privacy level for the video.
                artist:
                  type: string
                  description: Audio Only. Artist metadata for the audio track.
                album:
                  type: string
                  description: Audio Only. Album metadata for the audio track.
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/media/{media_ID}/delete:
    post:
      operationId: postSitesBySiteMediaByMediaIdDelete
      summary: 'Delete a piece of media. Note: Media is deleted and not trashed.'
      description: 'Delete a piece of media. Note: Media is deleted and not trashed.'
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Returns deleted if the media was successfully deleted
                  ID:
                    type: integer
                    description: The ID of the media item
                  date:
                    type: string
                    format: date-time
                    description: The date the media was uploaded
                  post_ID:
                    type: integer
                    description: ID of the post this media is attached to
                  author_ID:
                    type: integer
                    description: ID of the user who uploaded the media
                  URL:
                    type: string
                    description: URL to the file
                  guid:
                    type: string
                    description: Unique identifier
                  file:
                    type: string
                    description: File name
                  extension:
                    type: string
                    description: File extension
                  mime_type:
                    type: string
                    description: File mime type
                  title:
                    type: string
                    description: File name
                  caption:
                    type: string
                    description: User-provided caption of the file
                  description:
                    type: string
                    description: Description of the file
                  alt:
                    type: string
                    description: Alternative text for image files.
                  thumbnails:
                    type: object
                    description: Media item thumbnail URL options
                  height:
                    type: integer
                    description: (Image & video only) Height of the media item
                  width:
                    type: integer
                    description: (Image & video only) Width of the media item
                  length:
                    type: integer
                    description: (Video & audio only) Duration of the media item, in seconds
                  exif:
                    type: array
                    items: {}
                    description: (Image & audio only) Exif (meta) information about the media item
                  videopress_guid:
                    type: string
                    description: (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress
                  videopress_processing_done:
                    type: boolean
                    description: (Video only) If the video is Uuploaded on a blog with VideoPress, this will return the status of processing on the Video
        '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: media_ID
        in: path
        required: true
        schema:
          type: integer
        description: The media ID
      - 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.
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/media/{media_ID}/edit:
    post:
      operationId: postSitesBySiteMediaByMediaIdEdit
      summary: Edit a media item.
      description: Edit a media item.
      tags:
      - media
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The ID of the media item
                  date:
                    type: string
                    format: date-time
                    description: The date the media was uploaded
                  post_ID:
                    type: integer
                    description: ID of the post this media is attached to
                  author_ID:
                    type: integer
                    description: ID of the user who uploaded

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