エントリーの取得・作成・更新・削除


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

エントリーの基本の操作を説明します。本文(ユニット・ブロックエディター)とカスタムフィールドの値の形は エントリーの本文とカスタムフィールドを送る、公開・バージョン・承認フローは エントリーの公開・バージョン・承認フロー を参照してください。例では、環境変数 ACMS_API(https://example.com/rest-api/acms/v1)と ACMS_API_TOKEN を使います。

操作

メソッドとパス

スコープ

成功

一覧

GET /entries

entries:read

200

取得

GET /entries/{id}

entries:read

200(ETag 付き)

入力の規則の取得

GET /entries/editor-settings

entries:read

200

作成

POST /entries

entries:write(公開での作成は entries:publish も)

201(Location 付き)

更新

PATCH /entries/{id}・PUT /entries/{id}

entries:write(公開中のエントリーは entries:publish も)

200(承認フローで作業領域に保存したときは 202)

削除

DELETE /entries/{id}

entries:write(公開中のエントリーは entries:publish も)

204

ゴミ箱から戻す

POST /entries/{id}/restore

entries:write

200

複製

POST /entries/{id}/duplicate

entries:write

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

整数

不可

エントリー ID(作成の dry-run では null)

code

文字列(64 文字まで)

可

ファイル名。作成で省略すると、管理画面の新規作成と同じ規則(接頭辞 + ランダムな 8 文字 + 拡張子。例: entry-5tobfrnq.html)で付けます。空文字はファイル名なし(カテゴリーやブログのトップページ)

url

URL

不可

公開側の URL

status

open・close・draft・trash

可

ステータス(公開・非公開・下書き・ゴミ箱)。作成で省略すると、エントリー項目設定の既定(管理画面の新規作成と同じ)

approval

none・pre_approval

不可

承認前かどうか

title

文字列(255 文字まで)

可

タイトル。作成では必須(エントリー項目設定に既定のタイトルがあれば省略可)。文字数の上限は保存先のカテゴリーの編集画面の設定に従います

link_url

文字列 / null

可

リンク先 URL(255 文字まで)

blog_id

整数

不可

URL のブログで決まります

category_id

整数 / null

可

カテゴリー ID。タイトル・タグ・サブカテゴリー・リンク先 URL の入力の規則は、このカテゴリーの編集画面の設定で判定します

sub_category_ids

整数の配列

可

サブカテゴリー。配列ごと置き換えます

user_id

整数

可

投稿者。変えるには、管理画面で作成者を変更できる権限が要ります(無ければ 403)

tags

文字列の配列

可

タグ。配列ごと置き換えます

datetime

日時 / null

可

日時。null は現在の日時

start_datetime

日時 / null

可

公開日時。null は 1000-01-01 00:00:00(制限なし)

end_datetime

日時 / null

可

掲載期限。null は 9999-12-31 23:59:59(制限なし)

posted_datetime / updated_datetime

日時

不可

作成日時 / 更新日時

indexing

真偽値

可

インデキシング(一覧や検索の対象にするか)

members_only

真偽値

可

会員限定

is_public

真偽値

不可

公開中(公開・期間内・承認前でない)か

primary_image_unit_id

文字列 / null

可

メイン画像にするユニットの ID(units の中のもの)

units

ユニットの配列

可

本文。配列ごと置き換えます。body_html と同時には送れません

body_html

文字列

書き込みだけ

ブロックエディターの HTML。1 つのブロックエディターユニットとして保存します

fields

オブジェクト

可

カスタムフィールド。キーごとにマージし、null のキーは削除します

related_entries

{ "id": 整数, "type": 文字列 } の配列

可

関連エントリー。type は関連の種類(既定 default)。配列ごと置き換えます

links

オブジェクト

不可

self・blog・category・user の API の URL

embedded

オブジェクト

不可

include を付けたときだけ

warnings

配列

不可

書き込みの応答だけ。body_html の変換で出た警告(message・retryable・kind)

入力の規則を取得する(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 を取り直してください。