Top
Content API

GET /api/v1/{endpoint}

Last updated: 2026/04/27

In the list format API, you can retrieve a list of contents, while in the object format API, you can obtain a single content item.

For the object format API, you can get results similar to GET /api/v1/{endpoint}/{content_id}, so please refer to that for more information.
Here, we will explain the request headers, query parameters, and responses for the list format API.

Request Headers

X-MICROCMS-API-KEY

This is the authentication key required for GET API requests.
Please enable "GET" with default permissions or individual permissions and include it in the request headers when sending.

Caution: 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)".

Query Parameters

You can specify the parameters shown below in this API.
For a list of query parameters that can be specified for each field, please refer to "Specifying Query Parameters in the GET API".

Information: If a query parameter is added but no value is specified, it behaves the same as if the query parameter were not specified at all.
For example: specifying limit= sets the limit to the default value of 10.

draftKey

This is a parameter for retrieving content in draft status. Please add the draftKey that can be confirmed in the content editing screen as a parameter.
The draft content that can be retrieved using draftKey is usually only one.
If you want to retrieve multiple pieces of content in draft status at the same time, please enable "Retrieve All Drafts" with default permissions or individual permissions and make the request.

limit

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

Information: An error occurs when the response size (the value of content-length in the response header) exceeds approximately 5MB.

Tips: If you want to retrieve more than 101 items of content, please refer to "How can I retrieve more than 101 items of content?".

offset

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

orders

This will sort the content to be retrieved.
The default is the display order of content in the management screen (excluding the q parameter).

Specify the field name to be sorted in the format orders=publishedAt.
If you want to specify descending order, prepend the field name with - (minus).

Descending: -publishedAt
Ascending: publishedAt

Additionally, if you want to sort by multiple fields, specify them in a comma-separated format like orders=publishedAt,-updatedAt.

Information: If the values of the fields to be sorted by the orders parameter are the same, the order of the returned content is not guaranteed. In this case, to explicitly control the order, please consider using multiple fields for sorting, such as orders=publishedAt,-updatedAt.

Available Sort Orders

The fields and sort orders that can be sorted are as follows.
Behavior is undefined if other fields are specified.

User-Defined Fields

Text Field
Text Area
Date and Time
Number

Automatically Granted Fields

createdAt
publishedAt
updatedAt
revisedAt

Others

system:default (Content display order in the admin panel)

Sort Order When Specifying Fields Within Repeating Fields

When multiple custom fields are inserted, the values used for sorting differ between descending and ascending order.

Descending Order

Sorted in descending order based on the largest value among the values.

Ascending Order

Sorted in ascending order based on the smallest value among the values.

q

This parameter allows for full-text search of the content. It performs a search against an index created by morphological analysis of the registered data.
The response will be sorted and returned in the order of highest relevance to the keyword if the orders parameter is not specified.

About the Search Target

Search using the q parameter targets multiple fields rather than specific fields.
Details about the data being searched and the search logic are dependent on internal specifications and are therefore not publicly disclosed.

Additionally, the internal specifications may be subject to change at any time for the purpose of improving accuracy.

Information: Due to the specifications of morphological analysis, even if there are registered keywords that match the search terms, they may not be included in the search results depending on the word segmentation position.
If precise partial match searches are required, please consider using the contains option in the filters parameter.

fields

Specify the elements to retrieve within the content.
Please list the values separated by commas, such as fields=title,main_image,updatedAt,author.name. You can also specify elements of referenced content by connecting keys with dots, like author.organization.name. If fields is not specified, all elements will be retrieved.

Information: You cannot specify fields within a Custom Field.

ids

You can specify the content IDs as a comma-separated list like first_id,second_id,third_id to retrieve only the specified content.

filters

You can narrow down the content by specifying conditions. The available condition expressions are as follows.

Information: Currently, it is not possible to escape strings in the conditions specified within filters. Thank you for your understanding.

equals

Retrieves content that matches the specified criteria.
(e.g.: gender[equals]women)

not_equals

Retrieves content that does not match the specified criteria.
(e.g.: gender[not_equals]women)

contains

Retrieves content that contains the specified value.
(e.g.: title[contains]おすすめ)

Information

The search using contains checks each registered data one by one and returns data that matches the search criteria. If the text is long, if there are many pieces of content, or if combined with or and conditions, it may take time to return a response. If performance is a priority, please use the q parameter.
If the number of characters registered in the search target field is large (for example, exceeding 10,000 characters), there may be cases where it does not hit even if it matches the condition. For long text searches, please use the q parameter.
If the search target is a select field, partial match searches against the values of the options cannot be performed. Only options that match exactly will hit.
If the search target is a number field, it will not hit.

not_contains

Retrieves content that does not contain the specified value.
(e.g.: title[not_contains]おすすめ)

Information: Please check as there are similar precautions to those for contains.

less_than

Retrieves content that is less than the specified value.
(e.g.: createdAt[less_than]2023-11-23T03:00:00Z, count[less_than]25)

Information

When specifying a date and time, please use UTC. Note that time zone specifications are not allowed.
If the specified values are the same, they will not be retrieved.

greater_than

Fetches content greater than the specified value.
(e.g.: createdAt[greater_than]2023-11-23T03:00:00Z, count[greater_than]25)

Information

When specifying a date and time, please use UTC. Note that time zone specifications are not allowed.
If the specified values are the same, they will not be retrieved.

exists

Retrieves content where the specified value exists.
(e.g., nextLink[exists])

not_exists

Retrieves content where the specified value does not exist.
(e.g., nextLink[not_exists])

begins_with

Retrieves content that begins with the specified value.
(e.g., publishedAt[begins_with]2023-11)

Information: If the search target is a numeric field, it will not yield any results.

Advanced Usage of the filters Parameter

How to Specify Content Reference Fields

When using content reference/multiple content references and filtering based on the referenced content, please use:

For content reference, [equals] (e.g., category[equals]uN28Folyn)
For multiple content references, [contains] (e.g., tags[contains]oJIZmiban)

Please use Content ID for the filtering criteria. Other values cannot be used.

How to Specify Custom Fields

For custom fields, you can filter values within the custom field by using {Field ID}.{Field ID for filtering}[equals]{VALUE}.

How to Specify Repeating Fields

For repeating fields, you can filter values within the repeating field by using {Field ID}.{Custom Field ID}.{Field ID for filtering}[contains]{VALUE}.

How to Combine Conditional Expressions

Conditional expressions can be specified multiple times by separating them with [and] (AND condition) or [or] (OR condition).
You can also prioritize some expressions by enclosing them in parentheses ().

Example: Extract articles where the category is engineering and the date is after 2019/11/14 or where the title exists

$ curl  "https://{your-service}.microcms.io/api/v1/blog?filters=category[equals]engineering[and](date[begins_with]2019-11-14[or]title[exists])" -H "X-MICROCMS-API-KEY: {api-key}"

Information: The query parameters provided above are just a few examples. For the actual available query parameters, please refer to the "Specifying Query Parameters in the GET API".

depth

Specifies the depth of the hierarchy for retrieving reference content.
The minimum value is 0 and the maximum value is 3.
The default value is 1.

For example, if you are recursively referencing yourself to display related articles in blog content.

Example) When depth = 0

{
  "id": "id1",
  "title": "title1",
  "body": "body1",
  "related_blog": {
    "id": "id2"
  }
}

Example) When depth = 1

{
  "id": "id1",
  "title": "title1",
  "body": "body1",
  "related_blog": {
    "id": "id2",
    "title": "title2",
    "body": "body2",
    "related_blog": {
      "id": "id3"
    }
  }
}

Example) When depth = 2

{
  "id": "id1",
  "title": "title1",
  "body": "body1",
  "related_blog": {
    "id": "id2",
    "title": "title2",
    "body": "body2",
    "related_blog": {
      "id": "id3",
      "title": "title3",
      "body": "body3",
      "related_blog": {
        "id": "id4"
      }
    }
  }
}

richEditorFormat

You can change the response format of the old rich editor.
(Please note that the current rich editor does not support this.)

html (default)

If you specify html for richEditorFormat, you can retrieve it as HTML.
This is the default setting, and it will be applied if no parameters are specified.

{
    "title": "Update Information",
    "content": "<h2 id=\"h5ca2740170\">Hello World</h2><p>You can now <strong>change</strong> the format of the rich editor.<br><br><img src=\"https://images.microcms-assets.io/assets/9f54a34e853e4bee98b47ce18c0713f1/c22bcc0296204e81889119c2ffa9a883/domenico-loia-hGV2TfOh0ns-unsplash.jpg\" alt=\"\"><br></p>",
}

object

If you specify object for richEditorFormat, you can retrieve it in object format.

{
    "title": "Update Information",
    "content": {
        "contents": [
            {
                "type": "block",
                "value": [
                    {
                        "type": "text",
                        "value": "Hello World",
                        "attributes": {}
                    }
                ],
                "attributes": {
                    "header": 2
                }
            },
            {
                "type": "textBlock",
                "value": [
                    {
                        "type": "text",
                        "value": "You can now change the format of the rich editor.",
                        "attributes": {}
                    },
                    {
                        "type": "text",
                        "value": "Changed",
                        "attributes": {
                            "bold": true
                        }
                    },
                    {
                        "type": "text",
                        "value": "You can now change the format.",
                        "attributes": {}
                    },
                    {
                        "type": "text",
                        "value": "\n",
                        "attributes": {}
                    },
                    {
                        "type": "text",
                        "value": "\n",
                        "attributes": {}
                    }
                ]
            },
            {
                "type": "image",
                "value": "https://images.microcms-assets.io/assets/9f54a34e853e4bee98b47ce18c0713f1/c22bcc0296204e81889119c2ffa9a883/domenico-loia-hGV2TfOh0ns-unsplash.jpg",
                "attributes": {
                    "link": null,
                    "target": null,
                    "alt": null,
                    "width": 640,
                    "height": 427
            },
            },
        ]
    },
}

Information: We have confirmed a known issue where, when specifying object in richEditorFormat, sections that utilize nested list formats are not included in the response. We appreciate your understanding in this matter.

Response Body

Here is an example of a response.

{
    "contents": [
        {
            "id": "ywsd1lc_z",
            "createdAt": "2022-04-27T02:44:50.280Z",
            "updatedAt": "2022-04-27T02:44:50.280Z",
            "publishedAt": "2022-04-27T02:44:50.280Z",
            "revisedAt": "2022-04-27T02:44:50.280Z",
            "name": "Update Information"
        },
        {
            "id": "t9xe_ys44",
            "createdAt": "2022-04-27T02:44:50.197Z",
            "updatedAt": "2022-04-27T02:44:50.197Z",
            "publishedAt": "2022-04-27T02:44:50.197Z",
            "revisedAt": "2022-04-27T02:44:50.197Z",
            "name": "Tutorial"
        },
        {
            "id": "4sqeq8g36n8",
            "createdAt": "2022-04-27T02:44:50.068Z",
            "updatedAt": "2022-04-27T02:44:50.068Z",
            "publishedAt": "2022-04-27T02:44:50.068Z",
            "revisedAt": "2022-04-27T02:44:50.068Z",
            "name": "Technology"
        }
    ],
    "totalCount": 3,
    "offset": 0,
    "limit": 10
}

The values obtained from the API are returned in an array called contents. Additionally, the following values are included in the response.

For information on automatically assigned content IDs and date/time information, please refer to "Automatically Assigned Values for Content".
For details on the response format for each field, please refer to "GET API Field Response Formats".

Response Headers

Information: Only some of the response headers are listed. Please note that there are additional items that may be included beyond those mentioned.

x-current-date-time

This is the server-side time value at the time of the response. The format is ISO 8601.

x-current-date-time: 2023-01-01T00:00:00.000Z

Error Response

Please refer to the Content API error response.