This is an API that allows you to retrieve media information included in the service.

Request Header

X-MICROCMS-API-KEY

This is the authentication key required for GET API requests.
Please enable "Retrieve Media" with Management API permissions and include it in the request header when sending.

Response Example

This is an example of the response for the media list obtained from the Management API.

{
  "media": [
    {
      "id": "e803c1fa-368d-4087-b937-646db9f6e328",
      "createdAt": "2025-02-28T05:34:48.722Z",
      "updatedAt": "2026-04-08T01:32:39.694Z",
      "url": "https://images.microcms-assets.io/assets/9895824867684c2994e22452171b8c11/8f3b1b376ee84cc4acf12af148f9999d/sample1.png",
      "width": 1200,
      "height": 800,
      "tags": [
        "drawings",
        "animals"
      ]
    },
    {
      "id": "52d27e9a-5ada-4c22-9fe9-df2dec7ca1fd",
      "createdAt": "2026-04-08T01:32:10.812Z",
      "updatedAt": "2026-04-08T01:32:22.642Z",
      "url": "https://images.microcms-assets.io/assets/9895824867684c2994e22452171b8c11/d7bcc402720f471f9f36de5eca4057c5/sample2.png",
      "width": 1200,
      "height": 800,
      "alt": "walking with dog in the park",
      "tags": []
    }
  ],
  "totalCount": 2,
   "token": "FGluY2x1ZGVfY29ud...R0cHljVU5KUQ==" // Partially omitted
}

Query Parameters

You can specify parameters for this API.

limit

Specifies the number of items to retrieve.
The default value is 10. The maximum value is 100.

imageOnly

This parameter is used to specify that only images should be retrieved, excluding files such as videos and PDFs.
To retrieve only images, set it to true.
The default value is false.

fileName

This is a parameter for filtering by file name. It searches for file names that include the specified string along with the extension, and retrieves the matching media.
By default, no filtering is applied.

tags

This is a parameter for filtering by tags.
If multiple tags are specified as a comma-separated list, such as tags=drawings,animals, media with all the specified tags will be retrieved.
By default, no filtering is applied.

alt

This is a parameter for filtering by alternative text. It searches for media with alternative text that matches the specified string and retrieves the matching media.
By default, no filtering is applied.

token

This is a parameter for retrieving content from where the last request left off.
Please specify the value of token included in the initial response.

Subsequent Requests

If the limit and imageOnly parameters were included in the initial request, those conditions will be carried over even if they are not explicitly included in subsequent requests.