エントリーの取得・作成・更新・削除
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
エントリーの基本の操作を説明します。本文(ユニット・ブロックエディター)とカスタムフィールドの値の形は エントリーの本文とカスタムフィールドを送る、公開・バージョン・承認フローは エントリーの公開・バージョン・承認フロー を参照してください。例では、環境変数 ACMS_API(https://example.com/rest-api/acms/v1)と ACMS_API_TOKEN を使います。
操作 | メソッドとパス | スコープ | 成功 |
|---|---|---|---|
一覧 |
|
| 200 |
取得 |
|
| 200( |
入力の規則の取得 |
|
| 200 |
作成 |
|
| 201( |
更新 |
|
| 200(承認フローで作業領域に保存したときは 202) |
削除 |
|
| 204 |
ゴミ箱から戻す |
|
| 200 |
複製 |
|
| 201 |
一覧を取得する
curl -s -G "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
--data-urlencode "category_id=3" \
--data-urlencode "status=open" \
--data-urlencode "order=datetime-desc" \
--data-urlencode "limit=10" \
--data-urlencode "fields=id,title,url,datetime,tags"閲覧できるエントリーだけが返ります。非公開・下書きは閲覧権限があるときだけ、ゴミ箱は ?status=trash を付けたときだけです。要素は既定では本文(units)を含みません(?include=units で含めます)。使えるクエリの全部は REST API のリクエストとレスポンス を参照してください。子孫のブログのエントリーも含めるときは ?blog_axis=descendant を付けます。
1 件を取得する
curl -s -i "${ACMS_API}/entries/240/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"{
"id": 240,
"code": "rest-api-sample.html",
"url": "https://example.com/rest-api-doc/rest-api-sample.html",
"status": "draft",
"approval": "none",
"title": "REST API から作成したエントリー",
"link_url": null,
"blog_id": 1,
"category_id": 22,
"sub_category_ids": [],
"user_id": 1,
"tags": ["お知らせ", "サンプル"],
"datetime": "2026-11-12T10:00:00+09:00",
"start_datetime": "1000-01-01T00:00:00+09:00",
"end_datetime": "9999-12-31T23:59:59+09:00",
"posted_datetime": "2026-11-12T13:48:30+09:00",
"updated_datetime": "2026-11-12T13:48:30+09:00",
"indexing": true,
"members_only": false,
"is_public": false,
"primary_image_unit_id": "08360537-7dca-468d-87cb-96d8998257ff",
"units": [
{ "id": "71966e5d-524b-41dc-abdf-45d62c090221", "type": "text", "status": "open", "sort": 1, "align": "center", "group": null, "anker": "", "attributes": { "text_text": "見出しです", "text_tag": "h2" }, "children": [] },
{ "id": "a3949156-6aef-4260-a86a-f7cdb1f6d125", "type": "text", "status": "open", "sort": 2, "align": "center", "group": null, "anker": "", "attributes": { "text_text": "本文の段落です。", "text_tag": "p" }, "children": [] },
{ "id": "08360537-7dca-468d-87cb-96d8998257ff", "type": "media", "status": "open", "sort": 3, "align": "center", "group": null, "anker": "", "attributes": { "media_id": 36, "media_enlarged": "", "media_size": "" }, "children": [] }
],
"fields": {
"price": 1200,
"color": ["red", "blue"],
"event_date": "2026-12-01"
},
"related_entries": [],
"links": {
"self": "https://example.com/rest-api/acms/v1/entries/240/",
"blog": "https://example.com/rest-api/acms/v1/blogs/1/",
"category": "https://example.com/rest-api/acms/v1/categories/22/",
"user": "https://example.com/rest-api/acms/v1/users/1/"
}
}応答のヘッダーに ETag が付きます。更新・削除で If-Match に使います(安全に書き込むための仕組み)。閲覧できないエントリーは 404 です。ゴミ箱のエントリーは ?status=trash を付けたときだけ取得できます。
エントリーの表現の項目
キー | 型 | 書き込み | 説明 |
|---|---|---|---|
| 整数 | 不可 | エントリー ID(作成の dry-run では |
| 文字列(64 文字まで) | 可 | ファイル名。作成で省略すると、管理画面の新規作成と同じ規則(接頭辞 + ランダムな 8 文字 + 拡張子。例: |
| URL | 不可 | 公開側の URL |
|
| 可 | ステータス(公開・非公開・下書き・ゴミ箱)。作成で省略すると、エントリー項目設定の既定(管理画面の新規作成と同じ) |
|
| 不可 | 承認前かどうか |
| 文字列(255 文字まで) | 可 | タイトル。作成では必須(エントリー項目設定に既定のタイトルがあれば省略可)。文字数の上限は保存先のカテゴリーの編集画面の設定に従います |
| 文字列 / | 可 | リンク先 URL(255 文字まで) |
| 整数 | 不可 | URL のブログで決まります |
| 整数 / | 可 | カテゴリー ID。タイトル・タグ・サブカテゴリー・リンク先 URL の入力の規則は、このカテゴリーの編集画面の設定で判定します |
| 整数の配列 | 可 | サブカテゴリー。配列ごと置き換えます |
| 整数 | 可 | 投稿者。変えるには、管理画面で作成者を変更できる権限が要ります(無ければ 403) |
| 文字列の配列 | 可 | タグ。配列ごと置き換えます |
| 日時 / | 可 | 日時。 |
| 日時 / | 可 | 公開日時。 |
| 日時 / | 可 | 掲載期限。 |
| 日時 | 不可 | 作成日時 / 更新日時 |
| 真偽値 | 可 | インデキシング(一覧や検索の対象にするか) |
| 真偽値 | 可 | 会員限定 |
| 真偽値 | 不可 | 公開中(公開・期間内・承認前でない)か |
| 文字列 / | 可 | メイン画像にするユニットの ID( |
| ユニットの配列 | 可 | 本文。配列ごと置き換えます。 |
| 文字列 | 書き込みだけ | ブロックエディターの HTML。1 つのブロックエディターユニットとして保存します |
| オブジェクト | 可 | カスタムフィールド。キーごとにマージし、 |
|
| 可 | 関連エントリー。 |
| オブジェクト | 不可 |
|
| オブジェクト | 不可 |
|
| 配列 | 不可 | 書き込みの応答だけ。 |
入力の規則を取得する(editor-settings)
書き込みの前に、保存先のカテゴリーの「エントリー項目設定」(項目名・必須・上限・既定値)を取得できます。ブログ・カテゴリーの設定を管理画面と同じ順に重ねた結果です。
curl -s "${ACMS_API}/entries/editor-settings/?category_id=22" -H "Authorization: Bearer ${ACMS_API_TOKEN}"{
"blog_id": 1,
"category_id": 22,
"fields": {
"title": { "label": "タイトル", "help": "", "required": "save", "max_length": 255, "input": "single", "default": null },
"code": { "label": "ファイル名", "help": "" },
"status": { "label": "ステータス", "help": "", "default": "draft" },
"category_id": { "label": "カテゴリー", "help": "", "required": "none", "display": true },
"sub_category_ids": { "label": "サブカテゴリー", "help": "", "required": "none", "display": true, "limit": null, "default": [] },
"tags": { "label": "タグ", "help": "", "required": "none", "display": true, "limit": null, "default": [] },
"datetime": { "label": "日時", "help": "" },
"start_datetime": { "label": "公開日時", "help": "" },
"end_datetime": { "label": "掲載期限", "help": "" },
"indexing": { "label": "インデキシング", "help": "", "default": true },
"members_only": { "label": "会員限定", "help": "", "default": false },
"link_url": { "label": "リンク先URL", "help": "", "required": "none", "display": true, "default": null }
}
}required は none(任意)・save(保存時に必須)・publish(公開するときだけ必須)、limit は選択数の上限(null は無制限)、display は管理画面に出すかです(出さない項目は必須・上限の判定の対象になりません)。カスタムフィールドの定義は GET /field-definitions で取得します。
作成する
本文をファイル entry.json に書いて送ります。
{
"title": "新しいお知らせ",
"code": "news-20261112.html",
"status": "draft",
"category_id": 3,
"sub_category_ids": [5],
"tags": ["お知らせ", "イベント"],
"datetime": "2026-11-12T10:00:00+09:00",
"start_datetime": null,
"end_datetime": "2026-12-31T23:59:59+09:00",
"indexing": true,
"members_only": false,
"body_html": "<h2>概要</h2><p>イベントのお知らせです。</p>",
"fields": { "event_date": "2026-12-01", "price": 1200 },
"related_entries": [{ "id": 232 }]
}# 1. 保存せずに確かめる
curl -s -X POST "${ACMS_API}/entries/?dry_run=1" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
--data-binary @entry.json
# 2. 作成する(送り直しても二重に作らないよう Idempotency-Key を付ける)
curl -s -i -X POST "${ACMS_API}/entries/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
--data-binary @entry.json成功すると 201 と、Location: https://example.com/rest-api/acms/v1/entries/{新しい ID}/、作成したエントリーの表現(warnings を含む)が返ります。
送らなかった項目には、エントリー項目設定とカスタムフィールドの定義の既定値が入ります。
入力の規則(保存先のカテゴリーの編集画面の設定の必須・文字数・件数の上限、カスタムフィールドの定義の必須・検証)に違反すると 422
validation_failedで、errors[].pointerは#/title・#/tags・#/sub_category_ids・#/link_url・#/fields/{キー}などです。statusをopenにすると、公開時に必須の項目も判定し、entries:publishのスコープも要ります。承認フローが必要なブログ・カテゴリーでは、管理画面と同じく承認前のエントリーとして作成されます。
更新する
PATCH は、送った項目だけを変えます。tags・sub_category_ids・units・related_entries は配列ごと置き換え、fields はキーごとにマージします(null のキーは削除)。
ETAG=$(curl -s -D - -o /dev/null -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/entries/240/" \
| awk 'tolower($1)=="etag:"{print $2}' | tr -d '\r')
curl -s -X PATCH "${ACMS_API}/entries/240/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-H "If-Match: ${ETAG}" \
-d '{"title":"タイトルを変更しました","tags":["お知らせ"],"fields":{"price":1500,"old_key":null}}'入力の規則は、送らなかった項目も今の値と合わせて判定します。
送った
unitsは本文の全体として扱います。既存のユニットを残すときは、取得したユニットのidを付けて送ります(エントリーの本文とカスタムフィールドを送る)。本文の
statusをtrashにするとゴミ箱へ移り、ゴミ箱のエントリー(?status=trashを付けて呼ぶ)のstatusを変えるとゴミ箱から戻せます。変える前か後が公開中のエントリーの更新には、
entries:publishが要ります。公開中のエントリーをentries:writeだけで直したいときは、新しいバージョン(POST /entries/{id}/revisions)として保存し、公開は人に任せます。承認フローが必要で承認済みのエントリーは、管理画面と同じくメインを変えずに作業領域(リビジョン 1)へ保存し、202 とバージョンの表現を返します。
ほかのユーザーが編集ロックしていると 409
entry_lockedです。
PUT は全体の置き換えで、書き込める最上位の項目(code・status・title・link_url・category_id・sub_category_ids・user_id・tags・datetime・start_datetime・end_datetime・indexing・members_only・primary_image_unit_id・units・fields・related_entries)をすべて送ります。足りないと 422(code は required)です。fields は PUT でもキーごとにマージされます。
削除する・戻す・複製する
# ゴミ箱へ移す(既定)
curl -s -i -X DELETE "${ACMS_API}/entries/245/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# HTTP/2 204
# ゴミ箱のエントリーを取得する(?status=trash が無いと 404)
curl -s "${ACMS_API}/entries/245/?status=trash&fields=id,status" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# {"id":245,"status":"trash"}
# ゴミ箱から戻す(非公開として戻ります)
curl -s -X POST "${ACMS_API}/entries/245/restore/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# 完全に削除する(元に戻せません。ゴミ箱のエントリーなら ?status=trash も付ける)
curl -s -i -X DELETE "${ACMS_API}/entries/245/?force=true" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# 複製する(非公開のエントリーとして作られ、作成者はトークンのユーザー)
curl -s -i -X POST "${ACMS_API}/entries/240/duplicate/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"ゴミ箱に無いエントリーを戻そうとすると 409
conflict(detailは「エントリーはゴミ箱にありません。」)です。削除は「削除などの操作の上限」(既定 1 時間に 60 回)で数えます。本文で
statusをtrashにする更新も 1 回と数えます。公開中のエントリーの削除(ゴミ箱へ移すことを含む)には
entries:publishが要ります。複製は、承認フローが必要なブログ・カテゴリーでは承認前のエントリーとして作ります。
よくある質問・つまずき
作成で 422 になり、送っていないカスタムフィールドが指摘されます
カスタムフィールドの定義で「保存時に必須」の項目があります。errors[].pointer(例: #/fields/event_date)の項目を fields に入れて送ってください。定義はフィールドセットの表示条件(カテゴリーなど)で変わるため、category_id を変えると必須の項目も変わることがあります。
公開しようとすると 422 になります
「公開時に必須」の項目(エントリー項目設定・カスタムフィールドの定義で publish)が埋まっていません。errors の項目を埋めてから公開します。
タグを送ると 422 reserved になります
タグに予約語(rest-api・api などの URL の予約語、4 桁の数字、拡張子の付いた形)は使えません。また、タグ名にカンマ・スラッシュ・改行は使えません。
ファイル名(code)が重複してもエラーになりません
管理画面と同じく、コンフィグの check_duplicate_entry_code が on のときだけ、同じブログ・カテゴリーのコードの重複を 422(#/code、code は double、「同じコードのエントリーがあります。」)にします。off のサイトで重複を避けたいときは、作成の前に一覧で同じ code が無いかを確かめてください。
更新の応答に ETag が付きません
更新の応答には ETag を付けません。続けて更新するときは、もう一度 GET して ETag を取り直してください。