エントリーを書き込む、公開する

Content API では、エントリーを読むだけでなく、作る、変える、公開することもできます。ほかのシステムからエントリーを取り込むときや、入稿のツールを作るときに使います。

作ったり変えたりしたエントリーは、いつも下書きになります。公開するときは、公開の操作を別に呼びます。

前提

• 操作に合った権限のある API キー。権限の決め方は API キーを作る、権限を決める にあります

操作	要る権限
作る	［作成］
変える、下書きを捨てる	［更新］。PUT でエントリーを作るときは［作成］も
公開する、公開をやめる、予約する	［公開］
削除する	［削除］

• 書き込みの権限を持つキーは、サイトのサーバーやツールの中だけで使います。ブラウザに渡さないでください。

下の例では、<ホスト名> をあなたの環境のホスト名に、<API キー> を書き込みの権限のあるキーに置き換えてください。コンテンツタイプ ID は「posts」、フィールドは「title」（テキスト）と「body」（リッチテキスト）の例です。

操作の一覧

操作	メソッドと URL	返るもの
作る	POST /api/v1/content/<コンテンツタイプ ID>	201 とエントリー
置き換える。なければ作る	PUT /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>	200 か 201 とエントリー
一部を変える	PATCH /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>	200 とエントリー
公開する	POST /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>/publish	200 とエントリー
公開をやめる	POST /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>/unpublish	204
下書きを捨てる	DELETE /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>/draft	204
削除する	DELETE /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>	204
公開の日時を予約する	PUT /api/v1/content/<コンテンツタイプ ID>/<エントリー ID>/schedule	200

返るエントリーは、preview=true で読んだときと同じ値です。参照は入れずに返ります。

エントリーを作る

エントリー ID「hello」のエントリーを、下書きで作ります。本文は HTML で送れます。

curl https://<ホスト名>.hakocms.net/api/v1/content/posts \
  -H "Authorization: Bearer <API キー>" \
  -H "Content-Type: application/json" \
  -d '{"sys":{"id":"hello"},"title":"こんにちは","body":"<p>本文</p>"}'

201 と、作ったエントリーが返ります。Location ヘッダーに、エントリーの URL（/api/v1/content/posts/hello）が入ります。

{
  "sys": {
    "id": "hello",
    "contentType": "posts",
    "createdAt": "2026-10-08T05:00:00.000Z",
    "updatedAt": "2026-10-08T05:00:00.000Z",
    "publishedAt": null,
    "firstPublishedAt": null,
    "version": 1
  },
  "title": "こんにちは",
  "body": {
    "type": "doc",
    "content": [
      { "type": "paragraph", "content": [{ "type": "text", "text": "本文" }] }
    ]
  }
}

• sys.id を省くと、エントリー ID が自動で付きます。エントリー ID に使えるのは、英数字と -、_ の 1〜50 文字です
• 必須のフィールドは、下書きでは確かめません。公開するときに確かめます
• シングルのコンテンツタイプには POST を使えません。PUT か PATCH を使います

エントリーを変える

変え方は 2 つあります。

	送らなかったフィールド	エントリーがないとき
PUT	消える。送った値で置き換える	作る（201）
PATCH	そのまま。送ったフィールドだけ変える	404。シングルなら作る

タイトルだけを変えます。

curl -X PATCH https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>" \
  -H "Content-Type: application/json" \
  -d '{"title":"直したタイトル"}'

200 と、変えたあとのエントリーが返ります。

• 公開中のエントリーを変えると、「公開中（下書きあり）」になります。公開中の値は、公開するまで変わりません
• 公開をやめたエントリーにも、下書きを保存できます
• 本文に sys.id を入れるときは、URL のエントリー ID と同じにします。違うと 400 になります。読み取りの応答をそのまま送り返せるように、sys の contentType や createdAt などは無視されます
• PATCH で、本文が空だと 400 になります
• シングルは、エントリー ID のない URL（/api/v1/content/<コンテンツタイプ ID>）で PUT や PATCH を送れます

PATCH で値を消すときは、そのフィールドに null を送ります。配列は [] を送ると空になります。

{ "eyecatch": null, "tags": [] }

ほかの人の変更を上書きしない（sys.version）

本文に sys.version を入れると、エントリーの今の版がその番号のときだけ書き込みます。読んでから書くまでの間に、ほかの人や管理画面で変えられていたら、409 が返り、書き込みません。

curl -X PATCH https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>" \
  -H "Content-Type: application/json" \
  -d '{"sys":{"version":3},"title":"直したタイトル"}'

版の番号は、preview=true で読んだときの sys.version です。下書きがあれば下書きの版、なければ公開中の版です。PUT、PATCH、公開で使えます。

409 で version was changed by someone else が返ったら、エントリーを読み直し、変えたいところを当て直してから、もう一度送ります。

公開する

今の下書きを公開します。下書きがなければ、今の公開中の値をもう一度公開します。本文は省けます。

curl -X POST \
  https://<ホスト名>.hakocms.net/api/v1/content/posts/hello/publish \
  -H "Authorization: Bearer <API キー>"

200 と、公開したエントリーが返ります。

本文には、sys.version と sys.firstPublishedAt を入れられます。ほかの CMS から移るときに、もとの公開の日時を残したいときは、sys.firstPublishedAt を入れます。

curl https://<ホスト名>.hakocms.net/api/v1/content/posts/hello/publish \
  -H "Authorization: Bearer <API キー>" \
  -H "Content-Type: application/json" \
  -d '{"sys":{"firstPublishedAt":"2020-04-23T14:32:38.163Z"}}'

• 必須のフィールドがないなど、公開する値がスキーマに合わないときは 400 になります
• 公開するものがないときは 409 になります
• シングルを公開するときも、sys.id を使って /<エントリー ID>/publish の URL で送ります

公開をやめる、下書きを捨てる、削除する

公開をやめます。

curl -X POST \
  https://<ホスト名>.hakocms.net/api/v1/content/posts/hello/unpublish \
  -H "Authorization: Bearer <API キー>"

下書きを捨てて、公開中の値に戻します。

curl -X DELETE \
  https://<ホスト名>.hakocms.net/api/v1/content/posts/hello/draft \
  -H "Authorization: Bearer <API キー>"

エントリーを削除します。

curl -X DELETE https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>"

どれも、うまくいくと 204 が返ります。本文はありません。

次のときは 409 が返ります。

• 捨てる下書きがない
• 公開していないエントリーの公開をやめようとした
• ほかのエントリーから参照されているエントリーを削除しようとした

公開の日時を予約する

公開する日時と、公開をやめる日時を予約できます。

curl -X PUT \
  https://<ホスト名>.hakocms.net/api/v1/content/posts/hello/schedule \
  -H "Authorization: Bearer <API キー>" \
  -H "Content-Type: application/json" \
  -d '{"publishAt":"2026-10-20T09:00:00+09:00","closeAt":null}'

200 と、予約した publishAt と closeAt が返ります。

• publishAt は公開する日時、closeAt は公開をやめる日時です
• 送らなかったキーは変わりません。null を送ると、その予約を取り消します。知らないキーを送ると 422 になります
• 日時は先の日時にします。両方を入れるときは、publishAt を closeAt より前にします。違うと 400 になります
• publishAt を入れるときは、その時点の値で公開できるか（必須のフィールドがそろっているか）を確かめます
• 予約の時刻には、その時点のいちばん新しい下書きを公開します

送る値の形

読み取りで返る形のまま、送り返せます。そのほかに、次の書き方も使えます。

フィールドの種類	送る値
テキスト、テキストエリア	文字列
リッチテキスト	Hako Rich Text v1 の JSON か、HTML の文字列
画像、ファイル	{ "url": "<URL>" } か、URL の文字列
複数画像	画像の配列
日時	ISO 8601。UTC にそろえて保存します
真偽値、数値	true か false、数値
セレクト	選ぶ値の配列
参照	参照先のエントリー ID か、{ "sys": { "id": "<エントリー ID>" } }
複数参照	参照の配列
カスタム	fieldId を入れたオブジェクト
繰り返し	カスタムの配列

• リッチテキストを HTML で送ると、エディタで扱える形に変えて保存します。扱えない要素は中身の文字だけを残し、<script> などは捨てます
• リッチテキストを JSON で送ると、Hako Rich Text v1 の決まりで確かめます。合わないと 400 になり、details.issues に、どこが合わないか（body.content[0].attrs.level など）が入ります
• 画像とファイルには、外の URL も入れられます。Hako CMS のメディアの URL を入れるときは、同じスペースのメディアにします。画像のフィールドには画像を入れます。幅と高さ（ファイルは fileSize）は、メディアの値で補われます
• スキーマにないフィールドを送ると 400 になります

確かめる

書き込んだあとは、preview=true を付けて読むと、下書きの値を確かめられます（下書きを取る）。公開したあとは、preview=true を付けずに読むと、公開中の値を確かめられます（エントリーを取り出す）。

うまくいかないときは、次の表を見てください。

返ってきたもの	原因	直し方
403 forbidden（this API key cannot create entries など）	キーにその操作の権限がない	［API キー］の画面で、キーの権限を確かめます
400 bad_request	本文の値がスキーマに合わない、知らないフィールドがある、sys.id が URL と違う、など	message と details.issues の path で、どのフィールドかを確かめます
409 conflict	エントリー ID や一意の値が重なった、sys.version が違う、今の状態ではできない操作	message を見て、エントリーを読み直します
422 unprocessable_entity	本文の形が違う（知らないキーなど）	message を見て、本文のキーの綴りを確かめます

ほかのエラーは エラーの一覧 にあります。

関連

• エントリーを書く・公開する
• リッチテキストの形（Hako Rich Text v1）
• フィールドの種類と値の形
• Content API のリファレンス