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.
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.
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)".
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".
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.
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.
Specifies the number of items to retrieve.
The default value is 10. The maximum value is 100.
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 of content, please refer to "How can I retrieve more than 101 items of content?".
Shifts the starting position for content retrieval back by the specified value.
The default value is 0.
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).
-publishedAtpublishedAtAdditionally, if you want to sort by multiple fields, specify them in a comma-separated format like orders=publishedAt,-updatedAt.
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.
The fields and sort orders that can be sorted are as follows.
Behavior is undefined if other fields are specified.
createdAtpublishedAtupdatedAtrevisedAtsystem:default (Content display order in the admin panel)When multiple custom fields are inserted, the values used for sorting differ between descending and ascending order.
Sorted in descending order based on the largest value among the values.
Sorted in ascending order based on the smallest value among the values.
This is a parameter for searching content by keyword.
If the orders parameter is not specified, the response will be sorted and returned in the order of highest relevance to the keyword.
The 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.
q parameter searches are conducted on data created for full-text search based on the content. Due to the specifications of full-text search, search results may vary based on uppercase and lowercase letters, symbols, spaces, and how strings are separated. If you need an exact partial match search for a specific field, please consider using the filters parameter with contains.
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.
You cannot specify fields within a Custom Field.
Currently, it is not possible to escape strings in the conditions specified within filters. Thank you for your understanding.
Retrieves content that matches the specified criteria.
(e.g.: gender[equals]women)
Retrieves content that does not match the specified criteria.
(e.g.: gender[not_equals]women)
Retrieves content that contains the specified value.
(e.g.: title[contains]おすすめ)
Retrieves content that does not contain the specified value.
(e.g.: title[not_contains]おすすめ)
Please check as there are similar precautions to those for contains.
Retrieves content that is less than the specified value.
(e.g.: createdAt[less_than]2023-11-23T03:00:00Z, count[less_than]25)
Fetches content greater than the specified value.
(e.g.: createdAt[greater_than]2023-11-23T03:00:00Z, count[greater_than]25)
Retrieves content where the specified value exists.
(e.g., nextLink[exists])
Retrieves content where the specified value does not exist.
(e.g., nextLink[not_exists])
Retrieves content that begins with the specified value.
(e.g., publishedAt[begins_with]2023-11)
If the search target is a numeric field, it will not yield any results.
When using content reference/multiple content references and filtering based on the referenced content, please use:
Please use Content ID for the filtering criteria. Other values cannot be used.
For custom fields, you can filter values within the custom field by using {Field ID}.{Field ID for filtering}[equals]{VALUE}.
For repeating fields, you can filter values within the repeating field by using {Field ID}.{Custom Field ID}.{Field ID for filtering}[contains]{VALUE}.
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}"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".
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"
}
}
}
}You can change the response format of the old rich editor.
(Please note that the current rich editor does not support this.)
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>",
}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
},
},
]
},
}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.
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.
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.
The value of the specified number of items to retrieve.
The default value is 10.
The offset value for the specified starting position of retrieval.
The default value is 0.
Only some of the response headers are listed. Please note that there are additional items that may be included beyond those mentioned.
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.000ZPlease refer to the Content API error response.