Top
Management API (Beta)

POST /api/v1/apis

Last updated: 2026/09/01

This is the API for creating APIs for the Service.

Specifications

The main specifications regarding the API format, input limits, and contract plans are as follows.

APIs that can be created

The API format can be selected as either list (list format) or object (object format).
Field definitions are set at the same time as the API creation.

Basic API Settings

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	`apiFields` must specify at least one. No upper limit on the number of items. `customFields` can specify between 0 and 99 items.

Contract Plans and API Limits

Some field types may not be available depending on the contract plan.
If the number of APIs has reached the limit of the contract plan, you typically cannot create new APIs. For details on the limits, please refer to the Pricing Plan Page.
To allow exceeding the limit for an additional fee, specify the query parameter 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}”.

Request Headers

X-MICROCMS-API-KEY

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.

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 Permission Management)".

Content-Type

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

Query Parameters

allowAdditionalCharge

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
`false`	Does not allow creation with additional charges. This is the default value when the parameter is omitted.
`true`	Allows API creation with additional charges. Available on the Team plan, Business plan, and Enterprise plan.

If creating an API exceeds the limit of the contracted plan, the Team plan, Business plan, and Enterprise plan will return 402 Payment Required unless allowAdditionalCharge=true is specified.
For the Hobby plan and Template plan, 403 Forbidden will be returned regardless of the value specified for allowAdditionalCharge.

Request Body

Specify the basic information of the API, API fields, and custom fields as needed.

Top Level

Property	Type	Required	Description
`name`	string	Required	This is the API name. It should be specified with 1 to 300 characters.
`endpoint`	string	Required	This is the API endpoint. It should be specified with 3 to 32 characters consisting of lowercase letters, numbers, hyphens (`-`), and underscores (`_`). It must be unique within the same Service.
`type`	string	Required	This is the format of the API. Specify either `list` or `object`.
`apiFields`	array	Required	For details, please refer to apiFields below.
`customFields`	array	Optional	This is the definition of custom fields. Specify it when using fields of type `custom` or `repeater`. For details, please refer to customFields below.

If unknown properties or properties that cannot be used with each field type are specified, a 400 Bad Request will be returned.

apiFields

apiFields specifies the fields to be created in the API as an array.
In the following sections, we will explain the properties and constraints that can be specified in the JSON for each field type.

Common Properties

All fields have common properties in their JSON.

Example of JSON

{
 "fieldId": "title",
 "name": "Title",
 "kind": "text",
 "description": "Description",
 "required": true
}

Details of Properties

Property	Setting Item	Type	Required	Specifications/Constraints
`fieldId`	Field ID	string	Required	2 to 20 characters Reserved words `id`, `createdAt`, `updatedAt`, `publishedAt`, `revisedAt`, `fieldId` are not allowed (case insensitive) Only half-width uppercase letters, lowercase letters, numbers, hyphens (`-`), and underscores (`_`) are allowed Duplicate `fieldId` within the same `apiFields` is not allowed
`name`	Display Name	string	Required	1 to 100 characters
`kind`	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`	Description	string \| null	Optional	Empty string is not allowed If not set, specify either omit or `null`
`required`	Required Setting	boolean	Optional	-

Values that can be specified for the kind property and corresponding fields

Value of kind	Field	Document
`text`	Text Field	https://document.microcms.io/manual/text-field
`textArea`	Text Area	https://document.microcms.io/manual/textarea
`richEditorV2`	Rich Text Editor	https://document.microcms.io/manual/rich-editor-usage
`media`	Image	https://document.microcms.io/manual/image
`mediaList`	Multiple Images	https://document.microcms.io/manual/image-list
`file`	File	https://document.microcms.io/manual/file
`date`	Date	https://document.microcms.io/manual/date
`number`	Number	https://document.microcms.io/manual/number
`boolean`	Boolean	https://document.microcms.io/manual/boolean
`select`	Selectable Field	https://document.microcms.io/manual/select-field
`relation`	Content Reference	https://document.microcms.io/manual/relation
`relationList`	Multiple Content References	https://document.microcms.io/manual/relation-list
`iframe`	Extended Field	https://document.microcms.io/manual/field-extension
`custom`	Custom	https://document.microcms.io/manual/custom-field
`repeater`	Repeat	https://document.microcms.io/manual/repeat-field

Text Field

Example JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`isUnique`	Do not allow duplicates (unique)	boolean	Optional	Can be set to `true` for up to 5 fields within the same API
`patternMatchValidation`	Allow input of only specific patterns	object \| null	Optional	-
`patternMatchValidation.regexp.pattern`	Pattern	string	Optional	Specify a RE2-compatible regular expression Syntax not supported by RE2, such as lookbehind and backreferences, cannot be specified
`patternMatchValidation.regexp.flags`	Flags	string \| null	Optional	Only `g`/`i`/`m`/`s`/`u`/`y` can be specified If multiple are specified, they should be concatenated (e.g., `gi`) The flags reflected in the validation results are only `i`, `m`, and `s` `g`, `u`, and `y` can also be specified, but they do not affect the validation results Empty strings cannot be specified If not set, omit or specify `null`
`textSizeLimitValidation`	Limit the number of characters	object \| null	Optional	If setting a limit, at least one of `textSize.min` or `textSize.max` must have a value
`textSizeLimitValidation.textSize.min`	Minimum	number \| null	Optional	Integer greater than or equal to 0 If `max` is specified, `min <= max`
`textSizeLimitValidation.textSize.max`	Maximum	number \| null	Optional	Integer greater than or equal to 1 If `min` is specified, `max >= min`
`initialValue`	Initial Value	string \| null	Optional	Specify between 1 and 100 characters Empty strings cannot be specified If not setting an initial value, omit or specify `null`

Text Area

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`patternMatchValidation`	Allow input for specific patterns only	object \| null	Optional	-
`patternMatchValidation.regexp.pattern`	Pattern	string	Optional	Specify a RE2-compatible regular expression Syntax not supported by RE2, such as lookaheads and backreferences, cannot be specified
`patternMatchValidation.regexp.flags`	Flags	string \| null	Optional	Only `g`/`i`/`m`/`s`/`u`/`y` can be specified If multiple are specified, concatenate them (e.g., `gi`) The flags reflected in the validation results are only `i`, `m`, and `s` `g`, `u`, and `y` can also be specified, but they do not affect the validation results Empty strings cannot be specified If not set, omit or specify `null`
`textSizeLimitValidation`	Limit the number of characters	object \| null	Optional	When setting a limit, specify a value for at least one of `textSize.min` or `textSize.max`
`textSizeLimitValidation.textSize.min`	Minimum	number \| null	Optional	Integer greater than or equal to 0 If `max` is specified, `min <= max`
`textSizeLimitValidation.textSize.max`	Maximum	number \| null	Optional	Integer greater than or equal to 1 If `min` is specified, `max >= min`
`initialValue`	Initial Value	string \| null	Optional	Specify between 1 and 1,000 characters Empty strings cannot be specified If no initial value is set, omit or specify `null`

Rich Text Editor

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`richEditorV2Options`	Edit Toolbar	enum[]	Optional	Only specified decorations are enabled (at least one is required if explicitly specified) If omitted, all available decorations will be enabled. Refer to "Values that can be specified for the richEditorV2Options property and their corresponding decorations" for the values that can be specified An empty array `[]` cannot be specified Duplicate values cannot be specified
`richEditorV2ColorList`	Color Presets	object[]	Optional	Up to 20 items
`richEditorV2ColorList[].id`	Internal Identifier	string	Optional	Internal identifier If specified, a string of 10 characters consisting of alphanumeric characters, underscores (`_`), and hyphens (`-`) must be provided If omitted, a random ID in the same format will be automatically generated Empty strings and `null` cannot be specified Duplicate IDs cannot be specified within the same `richEditorV2ColorList`
`richEditorV2ColorList[].value`	Color	string	Conditionally Required	Required if the `richEditorV2ColorList` includes elements. Empty strings cannot be specified Specify a string in the format of `rgb(r, g, b)` or `rgba(r, g, b, a)` (note: include a space after the comma) Example: `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`
`richEditorV2HideColorPicker`	Show only color presets and hide the color picker	boolean	Optional	If set to true, at least one `richEditorV2ColorList` is required
`richEditorV2FontSizeList`	Font Size Presets	object[]	Optional	Up to 20 items
`richEditorV2FontSizeList[].id`	Internal Identifier	string	Optional	Internal identifier If specified, a string of 10 characters consisting of alphanumeric characters, underscores (`_`), and hyphens (`-`) must be provided If omitted, a random ID in the same format will be automatically generated Empty strings and `null` cannot be specified Duplicate IDs cannot be specified within the same `richEditorV2FontSizeList`
`richEditorV2FontSizeList[].name`	Display Name	string	Conditionally Required	Required if the `richEditorV2FontSizeList` includes elements. Empty strings cannot be specified At least one character
`richEditorV2FontSizeList[].value`	Size (%)	string	Conditionally Required	Required if the `richEditorV2FontSizeList` includes elements Integer string from 1 to 1000
`customClassList`	Custom Class	object[]	Optional	-
`customClassList[].id`	Internal Identifier	string	Optional	Internal identifier If specified, a string of 10 characters consisting of alphanumeric characters, underscores (`_`), and hyphens (`-`) must be provided If omitted, a random ID in the same format will be automatically generated Empty strings and `null` cannot be specified Duplicate IDs cannot be specified within the same `customClassList`
`customClassList[].name`	Display Name	string	Conditionally Required	Required if the `customClassList` includes elements. Empty strings cannot be specified
`customClassList[].value`	Class Name	string	Conditionally Required	Required if the `customClassList` includes elements. Empty strings cannot be specified

Values that can be specified for the richEditorV2Options property and their corresponding decorations

Value	Decoration/Function
`headerOne`	Heading 1
`headerTwo`	Heading 2
`headerThree`	Heading 3
`headerFour`	Heading 4
`headerFive`	Heading 5
`paragraph`	Paragraph
`bold`	Bold
`italic`	Italic
`underline`	Underline
`strike`	Strikethrough
`code`	Inline Code
`blockquote`	Quote
`codeBlock`	Code Block
`listBullet`	Bullet List
`listOrdered`	Numbered List
`link`	Link
`image`	Image
`file`	File
`table`	Table
`horizontalRule`	Horizontal Rule
`oembedly`	Embed (OEmbed)
`textAlign`	Text Alignment
`customClass`	Custom Class
`color`	Text Color
`size`	Text Size

Information: undo, redo, and clean are always valid fixed items and cannot be specified in richEditorV2Options. If specified, a 400 Bad Request will be returned. They are also not included in the response for GET and successful creation.

Image

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`imageSizeValidation`	Image Size Limit	object \| null	Optional	If setting a limit, at least one of `imageSize.width` or `imageSize.height` must have a value specified
`imageSizeValidation.imageSize.width`	width	number \| null	Optional	Integer greater than or equal to 1
`imageSizeValidation.imageSize.height`	height	number \| null	Optional	Integer greater than or equal to 1
`initialValue`	Initial Value	string \| null	Optional	Specify the URL of the image media uploaded to the same Service. URLs of non-image media cannot be specified In addition to the standard image delivery domain, URLs of custom domains set for the same Service can also be specified Empty strings cannot be specified If not setting an initial value, omit it or specify `null`

Multiple Images

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`mediaListLayout`	Layout	enum	Optional	Refer to "Values that can be specified for the mediaListLayout property and their corresponding decorations" for available values and corresponding layouts. If `mediaListLayout` is omitted, `HORIZONTAL_SCROLL` will be set. `null` cannot be specified.
`imageSizeValidation`	Image Size Limit	object \| null	Optional	To set a limit, at least one of `imageSize.width` or `imageSize.height` must have a value.
`imageSizeValidation.imageSize.width`	width	number \| null	Optional	Integer greater than or equal to 1
`imageSizeValidation.imageSize.height`	height	number \| null	Optional	Integer greater than or equal to 1
`initialValue`	Initial Value	string[]	Optional	Specify the URLs of image media uploaded to the same service. URLs of non-image media cannot be specified. In addition to the standard image delivery domain, URLs of custom domains set for the same service can also be specified. Up to 5 entries can be specified. Empty strings and `null` cannot be specified. If no initial value is set, omit it or specify an empty array `[]`.

Values that can be specified for the mediaListLayout property and their corresponding decorations

Value	Layout
`HORIZONTAL_SCROLL`	Horizontal (Scroll)
`GRID_2`	Horizontal (2 Columns)
`GRID_3`	Horizontal (3 Columns)
`GRID_4`	Horizontal (4 Columns)

File

Information: The File Field is available in the Team plan, Business plan, and Enterprise plan. It is not available in the Hobby plan.

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`initialValue`	Initial Value	string \| null	Optional	Specify the URL of files (including images) uploaded to the same Service In addition to the standard file delivery domain, you can also specify the URL of a custom domain set for the same Service Empty strings are not allowed If no initial value is set, omit it or specify `null`

Date

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`dateFormat`	Date only	boolean	Optional	`true`: Date only `false`: Date and time
`initialValue`	Initial Value	string \| null	Optional	Specify a date-time string in RFC 3339 format (e.g., `2026-08-05T00:00:00Z`) Date-only format (e.g., `2026-08-05`) is not allowed Specify in the same format even if `dateFormat` is `true`

Number

Example of JSON

{
  "fieldId": "price",
  "name": "Price",
  "kind": "number",
  "description": "The price of the product",
  "required": false,
  "numberSizeLimitValidation": { "numberSize": { "min": 100, "max": 10000 } },
  "initialValue": 10000
}

Property Details

Property	Setting Item	Type	Required	Specifications/Constraints
`numberSizeLimitValidation`	Limit numeric values	object \| null	Optional	If setting a limit, specify a value for at least one of `numberSize.min` or `numberSize.max`
`numberSizeLimitValidation.numberSize.min`	Minimum	number \| null	Optional	Specify an integer in the range of -9007199254740991 to 9007199254740991 If specifying `max`, then `min <= max`
`numberSizeLimitValidation.numberSize.max`	Maximum	number \| null	Optional	Specify an integer in the range of -9007199254740991 to 9007199254740991 If specifying `min`, then `max >= min`
`initialValue`	Initial Value	number \| null	Optional	Can be specified in the range of -9007199254740991 to 9007199254740991

Boolean

Example of JSON

{
  "fieldId": "isActive",
  "name": "Active",
  "kind": "boolean",
  "description": "This is a boolean value",
  "required": false,
  "initialValue":true
}

Property Details

Property	Setting Item	Type	Required	Specifications/Constraints
`initialValue`	Initial Value	boolean	Optional	-

Selectable Field

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`selectItems`	Options	object[]	Required	Empty array is allowed
`selectItems[].id`	Internal Identifier	string	Optional	If specified, must be a 10-character string consisting of half-width alphanumeric characters, underscores (_), or hyphens (-) If omitted, a random ID in the same format will be automatically generated Duplicate IDs within the same field are not allowed If referencing from `initialValue`, explicit ID specification is required Empty string and `null` are not allowed
`selectItems[].value`	Value of the Option	string	Conditionally Required	Required if `selectItems` contains elements
`multipleSelect`	Multiple Selection	boolean	Required	Set to `true` to allow multiple selections
`initialValue`	Initial Value	string[]	Optional	Must match values of `selectItems[].id` or specify `DEFAULT` Duplicate values are not allowed If `multipleSelect` is `false`, only one value can be specified Empty array is not allowed If no initial value is set, either omit the property or specify `["DEFAULT"]` If omitted, `["DEFAULT"]` will be set

Content Reference

Example of JSON

{
  "fieldId": "category",
  "name": "Category",
  "kind": "relation",
  "description": "The category associated with the article",
  "required": false,
  "referencedApiEndpoint": "categories",
  "listViewFieldId": "title"
}

Property Details

Property	Setting Item	Type	Required	Specifications/Constraints
`referencedApiEndpoint`	Referenced API	string	Required	Specify the endpoint of the referenced API that exists within the same Service The endpoint of the API being created cannot be specified If creating a self-referencing field, set it after the API is created
`listViewFieldId`	Item to display in the list view	string	Optional	Specify the `fieldId` of the field that exists in the referenced API. Field type does not matter If displaying the Content ID, specify `DEFAULT` Non-existent `fieldId` and empty strings cannot be specified If not set, it can be omitted

Multiple Content References

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`relationListCountLimitValidation`	Limit the number of multiple content references	object \| null	Optional	If setting a limit, specify a value for at least one of `relationListCount.min` or `relationListCount.max`
`relationListCountLimitValidation.relationListCount.min`	Minimum	number \| null	Optional	Integer greater than or equal to 0 If specifying `max`, then `min <= max`
`relationListCountLimitValidation.relationListCount.max`	Maximum	number \| null	Optional	Integer greater than or equal to 1 If specifying `min`, then `max >= min`
`referencedApiEndpoint`	Referenced API	string	Required	Specify the endpoint of the referenced API that exists within the same service The endpoint of the API being created cannot be specified For creating a self-referencing field, set it after the API is created
`listViewFieldId`	Item displayed in the list view	string	Optional	Specify the `fieldId` of a field that exists in the referenced API. Field type does not matter To display the content ID, specify `DEFAULT` Non-existent `fieldId` and empty strings cannot be specified If not set, it can be omitted

Extended Field

Example of JSON

{
  "fieldId": "embed",
  "name": "Embed",
  "kind": "iframe",
  "description": "An extended field that integrates with external tools",
  "required": false,
  "iframeUrl": "https://example.com/embed"
}

Property Details

Property	Setting Item	Type	Required	Specifications/Constraints
`iframeUrl`	Extended Field URL	string	Required	A string in URL format with http or https scheme, including the host

Custom

Links the data defined in customFields.

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`customFieldId`	Target custom field	string	Required	Specify the `fieldId` of the target data within customFields
`listViewFieldId`	Item to display on the list view	string	Optional	Specify the `fieldId` of the field of the target data within customFields. Field type does not matter To use the default display item, specify `DEFAULT` Non-existent `fieldId` and empty strings cannot be specified If not set, it can be omitted

Repeat

Multiple selections of data defined in customFields can be linked.

Example of JSON

{
  "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 Details

Property	Setting Item	Type	Required	Specifications/Constraints
`customFieldIds`	Target custom fields	string[]	Required	At least one is required Empty array is not allowed Duplicate `fieldId` is not allowed Specify the `fieldId` of the target data in customFields as an array
`repeaterCountLimitValidation`	Limit the number of repeating fields	object \| null	Optional	If setting a limit, specify a value for at least one of `repeatCount.min` or `repeatCount.max`
`repeaterCountLimitValidation.repeatCount.min`	Minimum	number	Optional	Integer greater than or equal to 0 If specifying `max`, then `min <= max`
`repeaterCountLimitValidation.repeatCount.max`	Maximum	number	Optional	Integer greater than or equal to 1 If specifying `min`, then `max >= min`

Notes

If the type of initialValue does not match the field type, a 400 Bad Request will be returned indicating the relevant field and property.
If you do not set an initial value, you should generally omit initialValue itself. Whether null can be specified depends on the property.
If validation is set, initialValue must also meet those conditions. If it does not satisfy conditions such as character count, regular expressions, or numerical ranges, a 400 Bad Request will be returned.

customFields

customFields specifies the definitions of custom fields as an array.

Property Details

Property	Setting Item	Type	Required	Specifications/Constraints
`customFields[].fieldId`	Custom Field ID	string	Required	Specify with 2 to 20 characters Reserved words `id`, `createdAt`, `updatedAt`, `publishedAt`, `revisedAt`, `fieldId` are not available (case insensitive) Only half-width uppercase letters, lowercase letters, numbers, hyphens (`-`), and underscores (`_`) are allowed Duplicate `fieldId` within the same `customFields` is not allowed
`customFields[].name`	Display Name	string	Required	Specify with 1 to 300 characters
`customFields[].fields`	Field Definition	object[]	Required	At least one must be specified. The settings for each field are the same as apiFields
`customFields[].fieldOrderByColumn`	Layout within Custom Fields	string[][]	Required	Display position of each field. For details, refer to "How to Specify Layout"

Layout Specification Method

Single Column Layout
To arrange all fields in a single vertical column, include only one array.

"fieldOrderByColumn": [
  ["field01", "field02", "field03"] 
]

Two Column Layout

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
]

Other Specifications

Specify all fieldId included in fields without duplication or omission.
The number of elements in the array can only be 1 or 2. These correspond to 1 column and 2 columns, respectively. Specifying 3 or more will result in an error.

Notes

customFields can specify up to 99 items.
If kind is custom, specify customFieldId; if repeater, specify customFieldIds with the same request's customFields[].fieldId.
If you specify a field ID that is not defined in customFields for customFieldId or customFieldIds, a 400 Bad Request will be returned.
At least one field must be specified in customFields[].fields. An empty array cannot be specified.
You cannot specify custom within a custom field.
In the text fields of customFields[].fields[], you cannot specify isUnique: true. Only false or omitting the key is allowed.

Request Example

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

Example Including Custom Fields

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

Response

If the API is created successfully, 201 Created will be returned.
The response body will be the schema of the created API, returned in the same format as when retrieving the API schema.
Each element of apiFields and customFields[].fields will include all properties corresponding to the field type. Properties omitted during the request will also be returned with default values or null.

Response Body

{
  "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": []
}

Status Code

Status Code	Description
`201 Created`	The API has been successfully created.
`400 Bad Request`	The request body is invalid. It may include missing required fields, type mismatches, unknown properties, or properties that do not correspond to the field types.
`402 Payment Required`	You have reached the API limit for your subscription plan. To allow creation with additional charges, specify `allowAdditionalCharge=true`.
`403 Forbidden`	The API Key does not have permission to create APIs, or it includes field types that are not available in your subscription plan.
`409 Conflict`	An API with the same endpoint already exists.

Error Response Example

For example, if a number is specified in the initialValue of the text field, the following response will be returned.

{ "message": "field \"title\": \"initialValue\" must be of type string" }

Contents

Specifications
APIs that can be created
Basic API Settings
Contract Plans and API Limits
API Schema Compatibility
Request Headers
X-MICROCMS-API-KEY
Content-Type
Query Parameters
allowAdditionalCharge
Request Body
Top Level
apiFields
customFields
Request Example
Response
Status Code