Content API のリファレンス

Content API は、サイトやアプリから、API キーでエントリーとメディアを読み書きするための API です。このページには、すべての操作と、その決まりを並べます。使い方の手順は、各項目からリンクしたページにあります。

ベース URL

https://<ホスト名>.hakocms.net/api/v1

<ホスト名> は、あなたの環境のホスト名です。管理画面のアドレス https://<ホスト名>.hakocms.net/admin と同じです。

スペースは、API キーから決まります。スペースをパスで示したいときは、/s/<スペースのスラッグ>/api/v1/… の形も使えます。キーのスペースと違うスラッグを書くと、401 が返ります。

認証

API キーを、次のどちらかのヘッダーで送ります。API キーの発行と権限は API キーを作る、権限を決める にあります。

ヘッダー	値
Authorization	Bearer <API キー>
X-HAKOCMS-API-KEY	<API キー>。前に別の認証があって Authorization が使えないとき

• 両方あるときは、X-HAKOCMS-API-KEY だけを見ます
• キーがない、違う、失効しているときは、401 が返ります

キーの権限	できること
read（［読み取り］）	公開中のエントリーを読む
preview（［プレビュー］）	preview=true で下書きも読む。read も要る
create（［作成］）	エントリーを作る
update（［更新］）	下書きを変える、捨てる
publish（［公開］）	公開する、公開をやめる、予約する
delete（［削除］）	エントリーを削除する
メディアの read create update delete	メディアの一覧と取得、アップロード、代替テキストとタグの変更、削除

どのオリジンからも呼べます（CORS：Access-Control-Allow-Origin: *）。ブラウザに渡してよいのは、［読み取り］だけのキーです。

操作の一覧

<タイプ> はコンテンツタイプ ID（画面の［エンドポイント］）、<ID> はエントリー ID です。

メソッドとパス	すること	権限	成功したとき	手順
GET /content/<タイプ>	コレクションの一覧。シングルならその 1 件	read	200	取り出す
GET /content/<タイプ>/<ID>	コレクションの 1 件	read	200	取り出す
POST /content/<タイプ>	作る（下書き）	create	201、Location ヘッダー	書き込む
PUT /content/<タイプ>/<ID>	下書きを置き換える。なければ作る	update（作るときは create も）	200 か 201	書き込む
PATCH /content/<タイプ>/<ID>	下書きの一部を変える	update	200	書き込む
PUT、PATCH /content/<シングル>	シングルを置き換える、一部を変える。なければ作る	同上	同上	書き込む
POST /content/<タイプ>/<ID>/publish	公開する	publish	200	書き込む
POST /content/<タイプ>/<ID>/unpublish	公開をやめる	publish	204	書き込む
PUT /content/<タイプ>/<ID>/schedule	公開と公開終了の日時を予約する	publish	200	書き込む
DELETE /content/<タイプ>/<ID>/draft	下書きを捨てる	update	204	書き込む
DELETE /content/<タイプ>/<ID>	削除する	delete	204	書き込む
GET /media	メディアの一覧	メディアの read	200
GET /media/<ID>	メディアを 1 件	メディアの read	200
POST /media	アップロード（multipart/form-data の file）	メディアの create	201、Location ヘッダー
PATCH /media/<ID>	代替テキストとタグを変える	メディアの update	200
DELETE /media/<ID>	メディアを削除する。エントリーで使っているものは消せない（409）	メディアの delete	204
GET /schema/openapi.json	スペースのコンテンツタイプから作った OpenAPI 3.1	どの権限でもよい	200
GET /schema/types.ts	同じく、TypeScript の型	どの権限でもよい	200

パスは、ベース URL /api/v1 からの続きです。

読み取りのクエリパラメーター

パラメーター	一覧	1 件、シングル	既定	決まり
limit	○		20	0〜100
offset	○		0
order	○		-sys.publishedAt。q があれば関連度の順	カンマ区切り。前に - で降順
where	○			絞り込みの式
q	○			全文検索の語。空白で区切るとすべてを含むもの
select	○	○	すべて	返すキーをカンマ区切りで。中はドットでたどる
include	○	○	1	参照を展開する段数。0〜3
richText	○	○	json	json か html
preview	○	○	false	true で下書きを返す。true か false で書く（1 や 0 は 400）

• 知らないパラメーターを付けると、400 が返ります
• 一覧だけのパラメーター（limit offset order where q）を 1 件やシングルに付けても、400 が返ります

使い方は、絞り込む、並べる、ページに分ける、全文検索を使う、参照の先も一緒に取る、下書きを取る（プレビュー） にあります。

order で並べられるもの

sys.id sys.createdAt sys.updatedAt sys.publishedAt sys.firstPublishedAt と、テキスト、テキストエリア、日時、数字のフィールドです。

• 文字列はバイトの順、数字は数の順、日時は時刻の順に比べます
• 値のないエントリーは、昇順でも降順でも後ろに並びます

where の書き方

やりたいこと	書き方
等しい、等しくない	category = "tech"、category != "tech"
大小	price < 1000、price <= 1000、price > 0、price >= 0
含む、含まない	title contains "Rust"、title not contains "Rust"
前方一致	title startsWith "Rust"
どれかに一致、どれにも一致しない	sys.id in ("a", "b")、category not in ("pr", "ad")
値がある、ない	eyecatch exists、eyecatch not exists
組み合わせ	and、or、not、かっこ ( )

• 文字列と日時は "…" か '…' で囲みます。中の引用符は \" \'、\ は \\ と書きます。数と true false は囲みません
• 日時は RFC 3339 か、日付だけ（その日の 0 時 UTC）で書きます
• 強さの順は not → and → or です
• 条件は 30 個、かっこと not の入れ子は 5 段、式は 2000 文字、in の値は 100 個までです
• フィールドの種類ごとに使える演算子は、フィールドの種類と値の形 にあります

メディアの一覧のパラメーター

パラメーター	既定	決まり
limit	20	1〜100
cursor		前の応答の nextCursor。付けると、ほかの絞り込みは無視し、最初の条件のまま続きを返す
kind		image で画像だけ
fileName		ファイル名の部分一致。大文字と小文字を区別しない
alt		代替テキストの部分一致
tags		カンマ区切り。すべてのタグを持つもの

返る値の形

一覧は、次の形で返ります。

{ "items": [], "total": 42, "limit": 20, "offset": 0 }

項目	中身
items	エントリーの配列
total	条件に当てはまる数。limit と offset で区切る前の数
limit offset	使った値

エントリーは、sys のあとに、フィールドがスキーマの順に並びます。

sys の項目	中身
id	エントリー ID
contentType	コンテンツタイプ ID
createdAt	作った日時
updatedAt	最後に保存した日時
publishedAt	今の公開版を公開した日時。公開していなければ null
firstPublishedAt	最初に公開した日時。公開していなければ null
version	返した値の版の番号。書き込みで、ほかの人の変更を上書きしないための確かめに使う

日時は、すべて UTC の ISO 8601 で、ミリ秒まで入ります（2026-10-08T06:10:00.000Z）。フィールドの値の形は フィールドの種類と値の形 にあります。

メディアは、次の形で返ります。メディアの一覧は { "items", "total", "limit", "nextCursor" } です。

{
  "sys": {
    "id": "k2m9x0a1b2c3",
    "createdAt": "2026-10-08T05:00:00.000Z",
    "updatedAt": "2026-10-08T05:00:00.000Z"
  },
  "url": "https://<メディアのホスト>/media/k2m9x0a1b2c3/hero.jpg",
  "fileName": "hero.jpg",
  "mimeType": "image/jpeg",
  "size": 182044,
  "kind": "image",
  "width": 1600,
  "height": 900,
  "alt": "トップの写真",
  "tags": ["top"]
}

項目	中身
url	配信の URL。管理画面とは別のホストになる。変換のパラメーターを付けられる（画像を変換して出す）
fileName	ファイル名。変えられない
mimeType	中身から判定した形式
size	大きさ（バイト）
kind	image（幅と高さが分かるもの）か file
width height	画像だけ
alt tags	代替テキストとタグ

アップロードしたメディアは、その時点で公開されます。URL を知っていれば、ログインも API キーもなしで、誰でも取得できます。

書き込みの決まり

• 作る、変えるは、いつも下書きになります。公開は publish で行います
• エントリー ID を省くと、ID が振られます。ID は英数字・-・_ の 1〜50 文字です
• 必須のフィールドは、下書きでは確かめません。公開するときに確かめます
• PUT は、送らなかったフィールドを消します。PATCH は、送ったフィールドだけを変えます
• 本文に sys.version を付けると、今の版がその番号のときだけ書き込みます。違えば 409 が返ります（PUT、PATCH、publish）
• publish の本文には、sys.version と sys.firstPublishedAt（最初に公開した日時を決めるとき）だけを書けます
• 予約（schedule）の本文は { "publishAt", "closeAt" } です。省いたものは変えず、null で取り消します。日時は未来で、両方あれば publishAt が先です
• スキーマにないフィールドを送ると、400 が返ります

上限

上限	超えたとき
URL の長さ：8 KB	414
読み取りの応答：5 MB	400。limit や select で減らす
1 回の一覧：100 件	limit は 100 まで

型の定義をダウンロードする

GET /schema/openapi.json は、スペースのコンテンツタイプごとのエントリーの型と、Content API とメディアの API のパスを持つ OpenAPI 3.1 を返します。これを使うと、各言語の道具でクライアントと型を作れます。

curl -fsS https://<ホスト名>.hakocms.net/api/v1/schema/openapi.json \
  -H "Authorization: Bearer <API キー>" \
  -o hakocms-openapi.json

• 型の名前は、コンテンツタイプ ID を PascalCase にしたものです（blog-posts は BlogPosts。数字で始まるときは前に T）
• スキーマを変えたら、取り直します。定義は、取った時点のスキーマから作られます
• 管理画面の［API キー］の画面からもダウンロードできます

互換性

同じ版（/api/v1）の中では、操作や項目を足すだけにします。項目や操作を消したり、必須にしたり、型や意味を変えたりはしません。形を変えるときは、更新履歴 で知らせます。

エラー

エラーは { "error": { "code", "message", "details" } } の形で返ります。コードごとの原因と直し方は エラーの一覧 にあります。

関連

• エントリーを取り出す
• エントリーを書き込む、公開する
• フィールドの種類と値の形
• Admin API のリファレンス