サービスにAPIを作成するAPIです。

仕様

APIの形式や入力上限、契約プランに関する主な仕様は次のとおりです。

作成できるAPI

• API形式は、list（リスト形式）または object（オブジェクト形式）から選択できます。
• APIの作成と同時に、フィールド定義を設定します。

APIの基本設定

契約プランとAPI数上限

• 一部のフィールド種別は、契約プランによって利用できない場合があります。
• API数が契約プランの上限に達している場合、通常はAPIを作成できません。上限については料金プランページをご覧ください。
• 追加料金による上限超過を許可する場合は、後述するクエリパラメータ allowAdditionalCharge=true を指定してください。

APIスキーマの互換性

リクエストとレスポンスには、APIスキーマ取得時と共通の形式を使用します。そのため、取得したAPIスキーマをもとに、別のサービスや環境へAPIを作成できます。
APIスキーマ取得のマネジメントAPIについては「GET /api/v1/apis/{endpoint}」をご確認ください。

リクエストヘッダー

X-MICROCMS-API-KEY

APIリクエストの際に必要な認証キーです。
マネジメントAPIの権限で「APIの作成」を有効にして、リクエストヘッダーに含めて送信してください。

Content-Type

送信するデータの形式を指定します。
microCMSではJSON形式のデータのみ扱っているため、application/json と指定してください。

クエリパラメータ

allowAdditionalCharge

API数が契約プランの上限に達している場合に、追加料金によるAPI作成を許可するかを指定します。Teamプラン、Businessプラン、Enterpriseプランで利用できます。

APIを作成すると契約プランの上限を超過する場合、Teamプラン、Businessプラン、Enterpriseプランでは、allowAdditionalCharge=true が指定されていないと 402 Payment Required が返却されます。
HobbyプランおよびTemplateプランでは、allowAdditionalCharge の指定値にかかわらず 403 Forbidden が返却されます。

リクエストボディ

APIの基本情報、APIフィールド、および必要に応じてカスタムフィールドを指定します。

トップレベル

未知のプロパティや、各フィールド種別で利用できないプロパティを指定した場合は、400 Bad Request が返却されます。

apiFields

apiFields には、APIに作成するフィールドを配列で指定します。
以降のセクションでは、各フィールドのJSONに指定可能なプロパティや制約を、フィールド種別ごとに説明します。

共通プロパティ

すべてのフィールドのJSONは、共通プロパティを持ちます。

JSONの例

{
 "fieldId": "title",
 "name": "タイトル",
 "kind": "text",
 "description": "説明文",
 "required": true
}

プロパティの詳細

kindプロパティに指定できる値と対応するフィールド

テキストフィールド

JSONの例

{
  "fieldId": "title",
  "name": "タイトル",
  "kind": "text",
　"description": "記事のタイトルです",
  "required": true,
  "isUnique": false,
  "patternMatchValidation": {
    "regexp": { "pattern": "^[A-Za-z0-9]+$", "flags": "gi" }
  },
  "textSizeLimitValidation": {
    "textSize": { "min": 1, "max": 50 }
  },
  "initialValue": "初期値のテキスト"
}

プロパティの詳細

テキストエリア

JSONの例

{
  "fieldId": "body",
  "name": "本文",
  "kind": "textArea",
　"description": "記事の本文です",
  "required": true,
  "patternMatchValidation": {
    "regexp": { "pattern": "^[A-Za-z0-9]+$", "flags": "gi" }
  },
  "textSizeLimitValidation": {
    "textSize": { "min": 0, "max": 1000 }
  }, 
　"initialValue": "初期値の本文"
}

プロパティの詳細

リッチエディタ

JSONの例

{
  "fieldId": "editor",
  "name": "リッチエディタ",
  "kind": "richEditorV2",
  "description": "記事の本文です",
  "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": "注釈", "value": "note" }]
}

プロパティの詳細

richEditorV2Optionsプロパティに指定できる値と対応する装飾

画像

JSONの例

{
  "fieldId": "thumbnail",
  "name": "サムネイル",
  "kind": "media",
  "description": "記事のサムネイル画像です",
  "required": true,
  "imageSizeValidation": { "imageSize": { "width": 600, "height": 400 } },
  "initialValue": "https://images.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/image.jpg"
}

プロパティの詳細

複数画像

JSONの例

{
  "fieldId": "gallery",
  "name": "ギャラリー",
  "kind": "mediaList",
  "description": "記事内で使用するギャラリーの画像を複数選択",
  "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"
  ]
}

プロパティの詳細

mediaListLayoutプロパティに指定できる値と対応する装飾

ファイル

JSONの例

{
  "fieldId": "attachment",
  "name": "添付ファイル",
  "kind": "file",
  "description": "記事内でダウンロードするファイル",
  "required": false,
  "initialValue": "https://files.microcms-assets.io/assets/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy/sample.pdf"
}

プロパティの詳細

日時

JSONの例

{
  "fieldId": "eventDate",
  "name": "開催日時",
  "kind": "date",
  "description": "コンテンツの日付です",
  "required": false,
  "dateFormat": true,
  "initialValue": "2026-07-03T09:00:00.000Z"
}

プロパティの詳細

数字

JSONの例

{
  "fieldId": "price",
  "name": "価格",
  "kind": "number",
  "description": "商品の価格です",
  "required": false,
  "numberSizeLimitValidation": { "numberSize": { "min": 100, "max": 10000 } },
  "initialValue": 10000
}

プロパティの詳細

真偽値

JSONの例

{
  "fieldId": "isActive",
  "name": "有効",
  "kind": "boolean",
  "description": "真偽値です",
  "required": false,
  "initialValue":true
}

プロパティの詳細

セレクトフィールド

JSONの例

{
  "fieldId": "category",
  "name": "カテゴリ",
  "kind": "select",
　"description": "記事のカテゴリです",
  "required": true,
  "selectItems": [
    { "id": "0HGv33ahx5", "value": "ニュース" },
    { "id": "9zB0S7w-HU", "value": "ブログ" }
  ],
  "multipleSelect": false,
  "initialValue": ["9zB0S7w-HU"]
}

プロパティの詳細

コンテンツ参照

JSONの例

{
  "fieldId": "category",
  "name": "カテゴリ",
  "kind": "relation",
  "description": "記事に紐づくカテゴリです",
  "required": false,
  "referencedApiEndpoint": "categories",
  "listViewFieldId": "title"
}

プロパティの詳細

複数コンテンツ参照

JSONの例

{
  "fieldId": "relatedArticles",
  "name": "関連記事",
  "kind": "relationList",
　"description": "記事に紐づく関連記事です", 
　"required": false,
  "relationListCountLimitValidation": {
    "relationListCount": { "min": 1, "max": 4 }
  },
  "referencedApiEndpoint": "articles",
  "listViewFieldId": "title"
}

プロパティの詳細

拡張フィールド

JSONの例

{
  "fieldId": "embed",
  "name": "埋め込み",
  "kind": "iframe",
  "description": "外部ツールと連携する拡張フィールドです",
  "required": false,
  "iframeUrl": "https://example.com/embed"
}

プロパティの詳細

カスタム

customFieldsで定義したデータを紐付けます。

JSONの例

{
  "fieldId": "authorProfile",
  "name": "著者プロフィール",
  "kind": "custom",
  "description": "著者プロフィールを入力するカスタムフィールドです",
  "required": false,
  "customFieldId": "profile",
  "listViewFieldId": "name"
}

プロパティの詳細

繰り返し

customFieldsで定義したデータを複数選択して紐付けます。

JSONの例

{
  "fieldId": "items",
  "name": "セクション",
  "kind": "repeater",
  "description": "見出しや本文などのブロックを繰り返し入力できます",
  "required": false,
  "customFieldIds": [
    "headingBlock",
    "bodyBlock"
  ],
  "repeaterCountLimitValidation": {
    "repeatCount": { "min": 1, "max": 10 }
  }
}

プロパティの詳細

注意事項

• initialValue の型がフィールド種別と一致しない場合は、対象のフィールドとプロパティを示す 400 Bad Request が返却されます。
• 初期値を設定しない場合は、原則として initialValue 自体を省略してください。null を指定できるかどうかはプロパティによって異なります。
• バリデーションを設定している場合、initialValue もその条件を満たす必要があります。文字数、正規表現、数値範囲などの条件を満たさない場合は、400 Bad Request が返却されます。

customFields

customFields には、カスタムフィールドの定義を配列で指定します。

プロパティの詳細

レイアウトの指定方法

1列配置
すべてのフィールドを縦一列に並べる場合、配列を1つだけ内包します。

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

2列配置

1つ目の配列が左列、2つ目の配列が右列に対応します。

"fieldOrderByColumn": [
  ["field01", "field02"], // 左側に表示
  ["field03"]             // 右側に表示
]

その他、仕様

• fields に含まれるすべての fieldId を重複や不足なく指定してください。
• 配列の要素数は1つ、または2つのみ指定可能です。それぞれ1カラム、2カラムに対応しています。3以上を指定するとエラーになります。

注意事項

• customFields は最大99件まで指定できます。
• kind が custom の場合は customFieldId、repeater の場合は customFieldIds に、同じリクエストの customFields[].fieldId を指定します。
• customFieldId または customFieldIds に、customFields で定義されていないフィールドIDを指定した場合は、400 Bad Request が返却されます。
• customFields[].fields には、1件以上のフィールドを指定します。空配列は指定できません。
• カスタムフィールド内に、custom を指定することはできません。
• customFields[].fields[] 内のテキストフィールドでは、isUnique: trueを指定できません。false またはキー省略のみ指定可能です。

リクエスト例

以下は、リスト形式のAPIを作成する例です。

curl -X POST "https://[サービスID].microcms-management.io/api/v1/apis" \
  -H "X-MICROCMS-API-KEY: [APIキー]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ブログ",
    "endpoint": "blog",
    "type": "list",
    "apiFields": [
      {
        "fieldId": "title",
        "name": "タイトル",
        "kind": "text",
        "required": true,
        "initialValue": "無題"
      },
      {
        "fieldId": "price",
        "name": "価格",
        "kind": "number",
        "initialValue": 1000
      },
      {
        "fieldId": "published",
        "name": "公開",
        "kind": "boolean",
        "initialValue": true
      },
      {
        "fieldId": "thumbnail",
        "name": "サムネイル",
        "kind": "media",
        "initialValue": "https://images.microcms-assets.io/assets/xxxx/yyyy/sample.png"
      }
    ]
  }'

カスタムフィールドを含む例

curl -X POST "https://[サービスID].microcms-management.io/api/v1/apis" \
  -H "X-MICROCMS-API-KEY: [APIキー]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "製品紹介",
    "endpoint": "products",
    "type": "list",
    "apiFields": [
      {
        "fieldId": "productName",
        "name": "製品名",
        "kind": "text",
        "required": true,
        "isUnique": true
      },
      {
        "fieldId": "seo",
        "name": "SEO設定",
        "kind": "custom",
        "customFieldId": "seoSettings"
      },
      {
        "fieldId": "faq",
        "name": "よくある質問",
        "kind": "repeater",
        "customFieldIds": ["faqItem"],
        "repeaterCountLimitValidation": {
          "repeatCount": {
            "min": 1,
            "max": 20
          }
        }
      }
    ],
    "customFields": [
      {
        "fieldId": "seoSettings",
        "name": "SEO設定",
        "fields": [
          {
            "fieldId": "metaTitle",
            "name": "メタタイトル",
            "kind": "text",
            "required": true
          },
          {
            "fieldId": "metaDescription",
            "name": "説明",
            "kind": "textArea"
          }
        ],
        "fieldOrderByColumn": [
          ["metaTitle"],
          ["metaDescription"]
        ]
      },
      {
        "fieldId": "faqItem",
        "name": "FAQ項目",
        "fields": [
          {
            "fieldId": "question",
            "name": "質問",
            "kind": "text",
            "required": true
          },
          {
            "fieldId": "answer",
            "name": "回答",
            "kind": "richEditorV2",
            "richEditorV2Options": ["bold", "link", "listBullet"]
          }
        ],
        "fieldOrderByColumn": [
          ["question"],
          ["answer"]
        ]
      }
    ]
  }'

レスポンス

正常にAPIを作成できた場合は、201 Created が返却されます。
レスポンスボディは、作成したAPIのスキーマです。APIスキーマ取得時と同じ形式で返却されます。
apiFields および customFields[].fields の各要素には、フィールド種別に対応するすべてのプロパティが含まれます。リクエスト時に省略したプロパティも、既定値または null で返却されます。

レスポンスボディ

{
  "name": "ブログ",
  "endpoint": "blog",
  "type": "list",
  "apiFields": [
    {
      "fieldId": "title",
      "name": "タイトル",
      "kind": "text",
      "description": null,
      "required": true,
      "textSizeLimitValidation": null,
      "patternMatchValidation": null,
      "isUnique": false,
      "initialValue": "無題"
    },
    {
      "fieldId": "price",
      "name": "価格",
      "kind": "number",
      "description": null,
      "required": false,
      "numberSizeLimitValidation": null,
      "initialValue": 1000
    },
    {
      "fieldId": "published",
      "name": "公開",
      "kind": "boolean",
      "description": null,
      "required": false,
      "initialValue": true
    },
    {
      "fieldId": "thumbnail",
      "name": "サムネイル",
      "kind": "media",
      "description": null,
      "required": false,
      "imageSizeValidation": null,
      "initialValue": "https://images.microcms-assets.io/assets/xxxx/yyyy/sample.png"
    }
  ],
  "customFields": []
}

ステータスコード

エラーレスポンス例

たとえば、text フィールドの initialValue に数値を指定した場合は、次のようなレスポンスが返却されます。

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