GET /api/v2/media
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.
CautionIf the X-MICROCMS-API-KEY is identifiable, it may allow unauthorized manipulation of content by third parties. Please handle it with care. For more details, please refer to "API Key (API Authentication and Authorization Management)".
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
}
InformationThe token will be included in the response during the initial request, even if there is no additional media information available.
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.
- Information
Valid only for the initial request (cannot be specified in subsequent requests with the token parameter attached).
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.
- Information
This is only valid for the initial request (it cannot be specified in subsequent requests with the token parameter attached).
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.
- Information
The token's validity period is 15 seconds (however, the token may remain valid for a certain period even after 15 seconds have passed).
TipsFor information on how to retrieve media information using a token, please refer to the help section "[Management API] Request Method Using Token for GET /api/v2/media".