Skip to content
SupaCMS Docs

API の使いかた

ベース URL

https://your-supacms.com/api/v1

認証

すべてのエンドポイントに Authorization ヘッダーが必要です。

Authorization: Bearer <api-key>

APIキーは管理画面の 設定 → APIキー から発行できます。

スペーススラッグ

エンドポイントの :spaceSlug は管理画面の 設定 → スペース で確認できます。

公開コンテンツ取得（読み取り専用）

フロントエンドからコンテンツを読み取る用途のエンドポイントです。公開済み（published）エントリのみ返します。

エントリ一覧

GET /api/v1/spaces/:spaceSlug/:contentTypeApiId/

レスポンス:

{
  "entries": [
    {
      "id": "01abc...",
      "fields": { "title": "記事タイトル" },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

エントリ取得

GET /api/v1/spaces/:spaceSlug/:contentTypeApiId/:entryId

管理 API

スキーマやエントリを作成・更新するエンドポイントです。CLI と同等の操作が API から直接行えます。

ContentType

メソッドパス説明
GET/spaces/:spaceSlug/content-types/一覧取得
POST/spaces/:spaceSlug/content-types/新規作成
PATCH/spaces/:spaceSlug/content-types/:ctApiId更新

POST リクエストボディ:

{
  "name": "ブログ記事",
  "apiId": "blogPost",
  "description": "任意の説明文"
}

apiId は英字始まり・英数字とアンダースコアのみ（例: blogPost, product_detail）。作成後に変更不可。

PATCH リクエストボディ:

{
  "name": "新しい表示名",
  "description": "新しい説明文"
}

apiId は変更できません。description は省略可能です。

フィールド

メソッドパス説明
GET/spaces/:spaceSlug/content-types/:ctApiId/fields/一覧取得
POST/spaces/:spaceSlug/content-types/:ctApiId/fields/追加
PATCH/spaces/:spaceSlug/content-types/:ctApiId/fields/:fieldApiId更新

POST リクエストボディ:

{
  "name": "タイトル",
  "apiId": "title",
  "required": true,
  "config": { "maxLength": 200 }
}

PATCH リクエストボディ:

{
  "name": "新しい表示名",
  "required": false,
  "config": { "maxLength": 300 }
}

apiId は変更できません。フィールドタイプと config の詳細は フィールドタイプ一覧 を参照してください。

エントリ

メソッドパス説明
GET/spaces/:spaceSlug/content-types/:ctApiId/entries/一覧取得
POST/spaces/:spaceSlug/content-types/:ctApiId/entries/作成（常に draft）
PATCH/spaces/:spaceSlug/content-types/:ctApiId/entries/:entryId更新
DELETE/spaces/:spaceSlug/content-types/:ctApiId/entries/:entryId削除
POST/spaces/:spaceSlug/content-types/:ctApiId/entries/:entryId/publish公開（draft → published）
POST/spaces/:spaceSlug/content-types/:ctApiId/entries/:entryId/unpublish非公開化（published → draft）

GET クエリパラメータ:

パラメータ値説明
statusdraft / publishedステータスでフィルタ（省略時は全件）

POST / PATCH リクエストボディ:

{
  "data": {
    "title": "記事タイトル",
    "body": "本文テキスト"
  }
}

エントリは常に draft で作成されます。/publish で公開状態に変更してください。すでに published のエントリに /publish を送ると 409 エラーになります。

APIキー

メソッドパス説明
GET/spaces/:spaceSlug/api-keys/一覧取得
POST/spaces/:spaceSlug/api-keys/新規作成

POST リクエストボディ:

{ "name": "プロダクション用" }

APIキーの値はレスポンスの key フィールドに含まれます。作成時のレスポンスにしか含まれません。安全な場所に保管してください。

メディア

メソッドパス説明
GET/spaces/:spaceSlug/media/一覧取得
POST/spaces/:spaceSlug/media/アップロード

POST リクエスト: multipart/form-data 形式

フィールド必須説明
file✓ファイル本体（JPEG / PNG / GIF / WebP / SVG、最大 10MB）
alt-代替テキスト（最大 500 文字）

レスポンス例:

{
  "id": "01938f...",
  "filename": "hero.png",
  "mimeType": "image/png",
  "size": 204800,
  "url": "/api/media/myspace/01938f...",
  "alt": "ヒーロー画像",
  "createdAt": "2026-08-05T09:00:00.000Z"
}

フィールド型のレスポンス形式

エントリの data フィールドには、ContentType に定義されたフィールドが含まれます。 各フィールドの型によって返す JSON 形式が異なります。

型レスポンス形式
short_text / long_text"文字列"
booleantrue / false
integer42
decimal3.14
datetime"2026-08-06T05:30:09.078Z"
url"https://example.com"
rich_text{ "type": "doc", "content": [...] } (Tiptap JSON)
json任意の JSON 値
media{ "id": "...", "url": "/api/media/<spaceId>/<mediaId>", "alt": "...", "size": 101108, "filename": "image.webp", "mimeType": "image/webp" }

media 型の注意

media 型の url は相対パスで返ります。フロントエンドで表示する際は、API のベースURL を先頭に付与してください:

const absoluteUrl = `${SUPACMS_API_URL}${media.url}`;
// 例: "https://supacms-website-prod-xxxx.supacms.workers.dev/api/media/myspace/01abc..."

optionalString(data.coverImage) のように文字列として扱うと [object Object] になります。 必ずオブジェクトとして処理してください。

// NG
const imgUrl = data.coverImage as string;


// OK
const media = data.coverImage as { url: string; alt: string | null };
const imgUrl = `${SUPACMS_API_URL}${media.url}`;

フロントエンド実装前の確認手順

フロントエンドから API を叩く前に、以下の手順で情報を確認してください。 これにより、URLの誤り・フィールド型の誤解・APIキーの問題を事前に発見できます。

Terminal window
# 1. スペースのAPIベースURLを確認
supacms space info --space <your-space-slug> --api-key <your-api-key> --pretty


# 2. コンテンツタイプの apiId を確認
supacms content-type list --space <your-space-slug> --api-key <your-api-key> --pretty


# 3. フィールド定義を確認（型に注意）
supacms field list \
  --space <your-space-slug> \
  --content-type <contentTypeApiId> \
  --api-key <your-api-key> \
  --pretty


# 4. 実際にAPIを叩いてレスポンス形式を確認
curl https://<apiBaseUrl>/api/v1/spaces/<spaceSlug>/<contentTypeApiId>/ \
  -H "Authorization: Bearer <api-key>" | jq '.entries[0].data'

エラーレスポンス

{ "error": "エラーメッセージ" }
ステータス説明
400リクエストボディが不正
401APIキーが無効
403スペースへのアクセス権がない
404リソースが見つからない
409apiId の重複 / 不正なステータス遷移
422エントリのバリデーションエラー（必須フィールド不足など）
500内部サーバーエラー