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.

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".

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.

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.

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.

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.

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.

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]おすすめ)

not_contains

Retrieves content that does not contain the specified value.
(e.g.: title[not_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)

greater_than

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

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)

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}"

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
            },
            },
        ]
    },
}

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.

totalCount

The total number of contents included in the API.
When using the filters parameter or the q parameter in the request, this will be the count of contents that match the criteria.

limit

The value of the specified number of items to retrieve.
The default value is 10.

offset

The offset value for the specified starting position of retrieval.
The default value is 0.

Response Headers

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.