By using the PATCH API, you can edit content via the API.

Request Header

X-MICROCMS-API-KEY

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

Content-Type

Specifies the format of the data being sent.
Since microCMS only handles data in JSON format, please specify application/json.

Query Parameters

status

This parameter is used to update or add draft content. Please add status=draft as a parameter.
For the behavior during updates, please refer to “Behavior for Each Status on Successful Requests.”

Request Body

Please prepare the JSON of the content you want to send according to the API schema and pass it as a string.
Example:

{"title":"Sample Title","category": ["Sample Category"]}

Field-Specific Specification Methods

Text Field

Please specify any string.
(Example: "Text 1")

Text Area

You can specify a multi-line string using newline characters.
(Example: "Input multiple lines of text\nInput multiple lines of text")

Rich Editor

You can specify decorations and images using HTML strings. For more details, please refer to the Rich Editor WRITE API.
(Example: "<h1>Heading</h1><p>You can submit in HTML like this</p>")

Old Rich Editor

You can specify a multi-line string using newline characters.
(Example: "Input multiple lines of text\nInput multiple lines of text")

Registration with HTML tags is not supported.
※If HTML is registered, it will be escaped as follows.
<p>Text 1</p> → ＆lt;p＆gt;Text 1＆lt;/p＆gt;

Image

Please specify the URL of the image uploaded to the same service of microCMS.
(Example: "https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample.png")

About Specifiable Image URLs

If a custom domain for media is set, both the custom domain and the default domain (microcms-assets.io) are accepted.

Also, specifying an invalid URL as follows will result in an error.

• URL of an image not uploaded to microCMS
• URL of an image uploaded to a different service of microCMS (※Services created with the multiple environment feature are also treated as different services)

Multiple Images

Please specify the URLs of images uploaded to the same service of microCMS as an array.
(Example: ["https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample1.png", "https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample2.png"])

The specifications for image URLs are the same as for the image field.

Date and Time

Please specify as a string in ISO format (ISO 8601).
(Example: "2020-04-23T14:32:38.163Z")

Number

Please specify a number.
(Example: 123)

Boolean

Please specify a boolean value.
(Example: true)

Select Field

Please specify the elements of the select field as an array.
(Example: ["Element 1","Element 2"])

Content Reference

Please specify the contentId of the referenced content.
(Example: "Referenced id")

Multiple Content References

Please specify the contentIds of the referenced contents as an array.
(Example: ["Referenced id 1","Referenced id 2"])

Custom Field

Please specify the content of the field you want to update in object format. Include fieldId and at least one value of the field you want to update.
(Example: { "fieldId": "YOURFIELDID", "some_value": "" })

Repeating Field

Please specify the target data as an array of custom fields. Each element of the array should include fieldId and all field values.
Example:

[
  {
    "fieldId": "YOURFIRSTFIELDID",
    "sometext_value": ""
  },
  {
    "fieldId": "YOUR_SECOND_FIELD_ID",
    "some_int_value": 10
  }
]

File

Please specify the URL of the media uploaded to the same microCMS service.
(Example: "https://files.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/manual.pdf")

About Specifiable File URLs

If a custom domain for media is set, both the custom domain and the default domain (microcms-assets.io) are accepted.

Additionally, specifying an invalid URL as follows will result in an error.

• URL of a file not uploaded to microCMS
• URL of a file uploaded to a different microCMS service (Note: Services created with the multiple environment feature are also treated as different services)

Extended Fields

Please specify the target data (the message part) in object format. You can update only the properties you want to change.
For details on each value, please refer to Extended Fields.
Example:

{
  "id": "some-id",
  "title": "some-title",
  "description": "some-description",
  "imageUrl": "https://images.microcms-assets.io/assets/xxxx/yyyy/{fileName}.png",
  "updatedAt": "2024-01-01T00:00:00Z",
  "data": { "id": "123" }
}

How to Specify Automatically Assigned Fields

Publication Date (publishedAt)

Please specify it as a string in ISO format (ISO 8601).
(Example: "2024-01-01T00:00:00Z")

How to Specify Empty Values for Fields

If you want to register a field value as empty in the PATCH API, please specify the following values according to the field type and make the request.

Response

If the content is created successfully, a 200 response will be returned.

Response Body

The response body when the request is executed successfully will be as follows:

{
    "id": "someId"
}

Behavior for Each Status Upon Successful Request

When a PATCH API request is successful, the behavior for each content status is as follows.

When Query Parameters Are Not Specified

When Specifying the Status Parameter

The behavior when requesting with status=draft is as follows.

Error Response

Please refer to the Content API Error Response.