microCMS

Tutorial
Next.js
Nuxt 3
Nuxt 2
Gatsby
Astro
Remix
JavaScript
PHP
Ruby
Go
iOS
Android
Manual
Account & Login
Services
Payment
API
Fields
Contents
Rich Editor
Reviews
Media
Permission Management
Connection
Logs
Security
Authentication
Specifications & Limitations
Content API
Basic Operations
API Keys
Responses & Error Handling
Management API (Beta)
Content Operations
Media Operations
Member Operations
API Operations
Service Operations
Responses & Error Handling
Image API
Parameters
MCP Server
  • Top
  • Management API (Beta)

GET /api/v1/media

Last updated: 2026/04/27

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

informationInformation

Starting from December 2023, we will provide a new endpoint for retrieving media information (GET api/v2/media). We recommend using this in the future.

cautionCaution

We have confirmed a known issue where if you try to retrieve more than 10,000 media items (by setting the offset to a value greater than 10,000), the data cannot be retrieved correctly.

To retrieve media information exceeding 10,000 items, please use GET /api/v2/media.

Request Header

X-MICROCMS-API-KEY

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

cautionCaution

If 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",
      "url": "https://images.microcms-assets.io/assets/9895824867684c2994e22452171b8c11/test.png",
      "width": 591,
      "height": 138
    },
    {
      "id": "52d27e9a-5ada-4c22-9fe9-df2dec7ca1fd",
      "url": "https://images.microcms-assets.io/assets/9895824867684c2994e22452171b8c11/d7bcc402720f471f9f36de5eca4057c5/example.png",
      "width": 808,
      "height": 177
    }
  ],
  "totalCount": 8,
  "limit": 2,
  "offset": 0
}


Query Parameters

This API allows you to specify parameters.

limit

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

informationInformation
  • An error occurs when the response size (the value of content-length in the response header) exceeds approximately 5MB.
  • If you want to retrieve more than 101 items, such as when fetching all items, please refer to the help below.

offset

Shifts the starting position for content retrieval back by the specified value.
The default value is 0.

imageOnly

This parameter is used when you want to retrieve only images, excluding files such as videos and PDFs.
To retrieve only images, specify true.
The default value is false.

Contents