This is the API for creating APIs for the Service.
The main specifications regarding the API format, input limits, and contract plans are as follows.
list (list format) or object (object format).Item | Constraints |
|---|---|
API Name | Specify a name that can be identified within the Service. |
Endpoint | Specify a unique value within the Service. The same value as an existing API cannot be used. |
Number of Fields |
|
allowAdditionalCharge=true as mentioned later.Requests and responses will use a common format as when obtaining the API schema. Therefore, you can create APIs for other services or environments based on the obtained API schema.
For the Management API to obtain the API schema, please check “GET /api/v1/apis/{endpoint}”.
This is the authentication key required for API requests.
Please enable "Create API" permission in the Management API 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 Permission Management)".
Specifies the format of the data being sent.
Since microCMS only handles data in JSON format, please specify application/json.
Specifies whether to allow the creation of APIs with additional charges when the number of APIs reaches the limit of the Service Plan. This feature is available on the Team plan, Business plan, and Enterprise plan.
Value | Description |
|---|---|
| Does not allow creation with additional charges. This is the default value when the parameter is omitted. |
| Allows API creation with additional charges. Available on the Team plan, Business plan, and Enterprise plan. |
To create an API that exceeds the API limit, specify allowAdditionalCharge=true for the Team plan, Business plan, or Enterprise plan. On the Hobby plan and Template plan, you cannot create an API that exceeds the API limit, regardless of the value specified for allowAdditionalCharge.
Specify the API's basic information, API fields, and custom fields as needed.
Property | Type | Required | Description |
|---|---|---|---|
| string | Required | This is the API name. It should be specified with 1 to 300 characters. |
| string | Required | This is the API endpoint. It should be specified with 3 to 32 characters consisting of lowercase letters, numbers, hyphens ( |
| string | Required | This is the format of the API. Specify either |
| array | Required | For details, please refer to apiFields below. |
| array | Optional | This is the definition of custom fields. Specify it when using fields of type |
Unknown properties and properties that are unavailable for a given field type cannot be specified.
In apiFields, specify the fields to create in the API as an array.
The following sections describe the properties and constraints that can be specified in each field's JSON, organized by field type.
All fields have common properties in their JSON.
{
"fieldId": "title",
"name": "Title",
"kind": "text",
"description": "Description",
"required": true
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Field ID | string | Required |
|
| Display Name | string | Required | 1 to 100 characters |
| Field Type | enum | Required | Refer to "Values that can be specified for the kind property and corresponding fields" for allowable values and corresponding fields |
| Description | string | null | Optional |
|
| Required Setting | boolean | Optional | - |
Value of kind | Field | Document |
|---|---|---|
| Text Field | |
| Text Area | |
| Rich Text Editor | |
| Image | |
| Multiple Images | |
| File | |
| Date | |
| Number | |
| Boolean | |
| Selectable Field | |
| Content Reference | |
| Multiple Content References | |
| Extended Field | |
| Custom | |
| Repeat |
{
"fieldId": "title",
"name": "Title",
"kind": "text",
"description": "This is the title of the article",
"required": true,
"isUnique": false,
"patternMatchValidation": {
"regexp": { "pattern": "^[A-Za-z0-9]+$", "flags": "gi" }
},
"textSizeLimitValidation": {
"textSize": { "min": 1, "max": 50 }
},
"initialValue": "Initial value text"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Do not allow duplicates (unique) | boolean | Optional | Can be set to |
| Allow input of only specific patterns | object | null | Optional | - |
| Pattern | string | Optional |
|
| Flags | string | null | Optional |
|
| Limit the number of characters | object | null | Optional | If setting a limit, at least one of |
| Minimum | number | null | Optional |
|
| Maximum | number | null | Optional |
|
| Initial Value | string | null | Optional |
|
{
"fieldId": "body",
"name": "Body",
"kind": "textArea",
"description": "This is the body of the article",
"required": true,
"patternMatchValidation": {
"regexp": { "pattern": "^[A-Za-z0-9]+$", "flags": "gi" }
},
"textSizeLimitValidation": {
"textSize": { "min": 0, "max": 1000 }
},
"initialValue": "Initial body text"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Allow input for specific patterns only | object | null | Optional | - |
| Pattern | string | Optional |
|
| Flags | string | null | Optional |
|
| Limit the number of characters | object | null | Optional | When setting a limit, specify a value for at least one of |
| Minimum | number | null | Optional |
|
| Maximum | number | null | Optional |
|
| Initial Value | string | null | Optional |
|
{
"fieldId": "editor",
"name": "Rich Text Editor",
"kind": "richEditorV2",
"description": "This is the body of the article",
"required": true,
"richEditorV2Options": ["paragraph", "bold", "link", "image", "color", "size"],
"richEditorV2ColorList": [{ "id": "f7Kp_2mQx9", "value": "rgb(255, 0, 0)" }],
"richEditorV2HideColorPicker": false,
"richEditorV2FontSizeList": [{ "id": "a9X-3vLmQ2", "name": "Large", "value": "120" }],
"customClassList": [{ "id": "N4cR_8zTp1", "name": "Note", "value": "note" }]
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Edit Toolbar | enum[] | Optional |
|
| Color Presets | object[] | Optional | Up to 20 items |
| Internal Identifier | string | Optional |
|
| Color | string | Conditionally Required |
|
| Show only color presets and hide the color picker | boolean | Optional | If set to true, at least one |
| Font Size Presets | object[] | Optional | Up to 20 items |
| Internal Identifier | string | Optional |
|
| Display Name | string | Conditionally Required |
|
| Size (%) | string | Conditionally Required |
|
| Custom Class | object[] | Optional | - |
| Internal Identifier | string | Optional |
|
| Display Name | string | Conditionally Required |
|
| Class Name | string | Conditionally Required |
|
Value | Decoration/Function |
|---|---|
| Heading 1 |
| Heading 2 |
| Heading 3 |
| Heading 4 |
| Heading 5 |
| Paragraph |
| Bold |
| Italic |
| Underline |
| Strikethrough |
| Inline Code |
| Quote |
| Code Block |
| Bullet List |
| Numbered List |
| Link |
| Image |
| File |
| Table |
| Horizontal Rule |
| Embed (OEmbed) |
| Text Alignment |
| Custom Class |
| Text Color |
| Text Size |
undo, redo, and clean are always enabled fixed items, so they cannot be specified in richEditorV2Options. They are also not included in GET responses or responses returned upon successful creation.
{
"fieldId": "thumbnail",
"name": "Thumbnail",
"kind": "media",
"description": "This is the thumbnail image for the article",
"required": true,
"imageSizeValidation": { "imageSize": { "width": 600, "height": 400 } },
"initialValue": "https://images.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/image.jpg"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Image Size Limit | object | null | Optional | If setting a limit, at least one of |
| width | number | null | Optional | Integer greater than or equal to 1 |
| height | number | null | Optional | Integer greater than or equal to 1 |
| Initial Value | string | null | Optional |
|
{
"fieldId": "gallery",
"name": "Gallery",
"kind": "mediaList",
"description": "Select multiple images for the gallery used in the article",
"required": false,
"mediaListLayout": "GRID_3",
"imageSizeValidation": { "imageSize": { "width": 400, "height": 600 } },
"initialValue": [
"https://images.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/image-01.jpg",
"https://images.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/image-02.jpg"
]
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Layout | enum | Optional |
|
| Image Size Limit | object | null | Optional | To set a limit, at least one of |
| width | number | null | Optional | Integer greater than or equal to 1 |
| height | number | null | Optional | Integer greater than or equal to 1 |
| Initial Value | string[] | Optional |
|
Value | Layout |
|---|---|
| Horizontal (Scroll) |
| Horizontal (2 Columns) |
| Horizontal (3 Columns) |
| Horizontal (4 Columns) |
The File Field is available in the Team plan, Business plan, and Enterprise plan. It is not available in the Hobby plan.
{
"fieldId": "attachment",
"name": "Attached File",
"kind": "file",
"description": "File to be downloaded within the article",
"required": false,
"initialValue": "https://files.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/sample.pdf"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Initial Value | string | null | Optional |
|
{
"fieldId": "eventDate",
"name": "Event Date and Time",
"kind": "date",
"description": "The date of the content",
"required": false,
"dateFormat": true,
"initialValue": "2026-07-03T09:00:00.000Z"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Date only | boolean | Optional |
|
| Initial Value | string | null | Optional |
|
{
"fieldId": "price",
"name": "Price",
"kind": "number",
"description": "The price of the product",
"required": false,
"numberSizeLimitValidation": { "numberSize": { "min": 100, "max": 10000 } },
"initialValue": 10000
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Limit numeric values | object | null | Optional | If setting a limit, specify a value for at least one of |
| Minimum | number | null | Optional |
|
| Maximum | number | null | Optional |
|
| Initial Value | number | null | Optional |
|
{
"fieldId": "isActive",
"name": "Active",
"kind": "boolean",
"description": "This is a boolean value",
"required": false,
"initialValue":true
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Initial Value | boolean | Optional | - |
{
"fieldId": "category",
"name": "Category",
"kind": "select",
"description": "This is the category of the article.",
"required": true,
"selectItems": [
{ "id": "0HGv33ahx5", "value": "News" },
{ "id": "9zB0S7w-HU", "value": "Blog" }
],
"multipleSelect": false,
"initialValue": ["9zB0S7w-HU"]
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Options | object[] | Required | Empty array is allowed |
| Internal Identifier | string | Optional |
|
| Value of the Option | string | Conditionally Required | Required if |
| Multiple Selection | boolean | Required | Set to |
| Initial Value | string[] | Optional |
|
{
"fieldId": "category",
"name": "Category",
"kind": "relation",
"description": "The category associated with the article",
"required": false,
"referencedApiEndpoint": "categories",
"listViewFieldId": "title"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Referenced API | string | Required |
|
| Item to display in the list view | string | Optional |
|
{
"fieldId": "relatedArticles",
"name": "Related Articles",
"kind": "relationList",
"description": "Related articles linked to the article",
"required": false,
"relationListCountLimitValidation": {
"relationListCount": { "min": 1, "max": 4 }
},
"referencedApiEndpoint": "articles",
"listViewFieldId": "title"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Limit the number of multiple content references | object | null | Optional | If setting a limit, specify a value for at least one of |
| Minimum | number | null | Optional |
|
| Maximum | number | null | Optional |
|
| Referenced API | string | Required |
|
| Item displayed in the list view | string | Optional |
|
{
"fieldId": "embed",
"name": "Embed",
"kind": "iframe",
"description": "An extended field that integrates with external tools",
"required": false,
"iframeUrl": "https://example.com/embed"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Extended Field URL | string | Required | A string in URL format with http or https scheme, including the host |
Links the data defined in customFields.
{
"fieldId": "authorProfile",
"name": "Author Profile",
"kind": "custom",
"description": "This is a custom field for entering the author profile.",
"required": false,
"customFieldId": "profile",
"listViewFieldId": "name"
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Target custom field | string | Required | Specify the |
| Item to display on the list view | string | Optional |
|
Multiple selections of data defined in customFields can be linked.
{
"fieldId": "items",
"name": "Section",
"kind": "repeater",
"description": "You can repeatedly enter blocks such as headings and body text.",
"required": false,
"customFieldIds": [
"headingBlock",
"bodyBlock"
],
"repeaterCountLimitValidation": {
"repeatCount": { "min": 1, "max": 10 }
}
}Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Target custom fields | string[] | Required |
|
| Limit the number of repeating fields | object | null | Optional | If setting a limit, specify a value for at least one of |
| Minimum | number | Optional |
|
| Maximum | number | Optional |
|
initialValue.initialValue itself in principle. Whether you can specify null depends on the property.initialValue must also meet the specified conditions, such as character count, regular expressions, and numeric ranges.Property | Setting Item | Type | Required | Specifications/Constraints |
|---|---|---|---|---|
| Custom Field ID | string | Required |
|
| Display Name | string | Required | Specify with 1 to 300 characters |
| Field Definition | object[] | Required | At least one must be specified. The settings for each field are the same as apiFields |
| Layout within Custom Fields | string[][] | Required | Display position of each field. For details, refer to "How to Specify Layout" |
Single-column layout
To arrange all fields in a single vertical column, include only one array.
"fieldOrderByColumn": [
["field01", "field02", "field03"]
]The first array corresponds to the left column, and the second array corresponds to the right column.
"fieldOrderByColumn": [
["field01", "field02"], // Displayed on the left
["field03"] // Displayed on the right
]fieldId included in fields exactly once.customFields.kind is custom, specify the customFields[].fieldId from the same request in customFieldId. When kind is repeater, specify it in customFieldIds.customFields[].fields. Empty arrays are not allowed.custom inside a custom field.customFields[].fields[], you cannot specify isUnique: true. Only false or omitting the key is allowed.Below is an example of creating a list-type API.
curl -X POST "https://[Service ID].microcms-management.io/api/v1/apis" \
-H "X-MICROCMS-API-KEY: [API Key]" \
-H "Content-Type: application/json" \
-d '{
"name": "Blog",
"endpoint": "blog",
"type": "list",
"apiFields": [
{
"fieldId": "title",
"name": "Title",
"kind": "text",
"required": true,
"initialValue": "Untitled"
},
{
"fieldId": "price",
"name": "Price",
"kind": "number",
"initialValue": 1000
},
{
"fieldId": "published",
"name": "Published",
"kind": "boolean",
"initialValue": true
},
{
"fieldId": "thumbnail",
"name": "Thumbnail",
"kind": "media",
"initialValue": "https://images.microcms-assets.io/assets/xxxx/yyyy/sample.png"
}
]
}'curl -X POST "https://[Service ID].microcms-management.io/api/v1/apis" \
-H "X-MICROCMS-API-KEY: [API Key]" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Introduction",
"endpoint": "products",
"type": "list",
"apiFields": [
{
"fieldId": "productName",
"name": "Product Name",
"kind": "text",
"required": true,
"isUnique": true
},
{
"fieldId": "seo",
"name": "SEO Settings",
"kind": "custom",
"customFieldId": "seoSettings"
},
{
"fieldId": "faq",
"name": "Frequently Asked Questions",
"kind": "repeater",
"customFieldIds": ["faqItem"],
"repeaterCountLimitValidation": {
"repeatCount": {
"min": 1,
"max": 20
}
}
}
],
"customFields": [
{
"fieldId": "seoSettings",
"name": "SEO Settings",
"fields": [
{
"fieldId": "metaTitle",
"name": "Meta Title",
"kind": "text",
"required": true
},
{
"fieldId": "metaDescription",
"name": "Description",
"kind": "textArea"
}
],
"fieldOrderByColumn": [
["metaTitle"],
["metaDescription"]
]
},
{
"fieldId": "faqItem",
"name": "FAQ Item",
"fields": [
{
"fieldId": "question",
"name": "Question",
"kind": "text",
"required": true
},
{
"fieldId": "answer",
"name": "Answer",
"kind": "richEditorV2",
"richEditorV2Options": ["bold", "link", "listBullet"]
}
],
"fieldOrderByColumn": [
["question"],
["answer"]
]
}
]
}'If the API is created successfully, 201 Created is returned.
The response body contains the schema of the created API. It is returned in the same format as when retrieving an API Schema.
Each item in apiFields and customFields[].fields includes all properties corresponding to its field type. Properties omitted from the request are also returned with their default values or as null.
{
"name": "Blog",
"endpoint": "blog",
"type": "list",
"apiFields": [
{
"fieldId": "title",
"name": "Title",
"kind": "text",
"description": null,
"required": true,
"textSizeLimitValidation": null,
"patternMatchValidation": null,
"isUnique": false,
"initialValue": "Untitled"
},
{
"fieldId": "price",
"name": "Price",
"kind": "number",
"description": null,
"required": false,
"numberSizeLimitValidation": null,
"initialValue": 1000
},
{
"fieldId": "published",
"name": "Published",
"kind": "boolean",
"description": null,
"required": false,
"initialValue": true
},
{
"fieldId": "thumbnail",
"name": "Thumbnail",
"kind": "media",
"description": null,
"required": false,
"imageSizeValidation": null,
"initialValue": "https://images.microcms-assets.io/assets/xxxx/yyyy/sample.png"
}
],
"customFields": []
}