Kuroco API Content

Kuroco API連携 & コンテンツ管理

Kuroco HeadlessCMSのAPI設計・実装およびコンテンツ管理に関するベストプラクティス。

ドキュメント参照: /kuroco-docs スキルを使用してKuroco公式ドキュメントを検索・参照できます。

目次

Part 1: API連携パターン

• エンドポイント設計
• セキュリティ設定
• キャッシュ戦略
• 流量制限
• API呼び出しパターン
• エラーハンドリング

Part 2: コンテンツ管理パターン

• コンテンツ構造
• 拡張項目（カスタムフィールド）
• Topics API オペレーション
• コンテンツCRUD操作
• フィルタークエリ → 詳細は references/filter-query.md
• ファイル・CSV操作 → 詳細は references/file-operations.md
• Admin MCPによる管理操作（コンテンツ）

Part 1: API連携パターン

エンドポイント設計

基本構造

KurocoのAPIパスは以下の形式：

https://{サイトキー}.g.kuroco.app/rcms-api/{api_id}/{endpoint_path}

例：

https://example.g.kuroco.app/rcms-api/1/news
https://example.g.kuroco.app/rcms-api/1/member/login

エンドポイント設定の主要項目

主要カテゴリとモデル

認証（Authentication）

コンテンツ（Topics）

メンバー（Member）

フォーム（InquiryMessage/InquiryForm）

ECポイント（ECPoint）

セキュリティ設定

詳細リファレンス: セキュリティ設定の詳細は references/security-settings.md を参照してください。

公式ドキュメント: 詳細な公式情報は ../kuroco-docs/docs/management-api.md（api-security） 等を参照してください。

認証方式

管理画面: [API] → [セキュリティ] で4種類から選択。

トークン有効期限の事前通知: 静的アクセストークン・特権付き静的トークン・KurocoFrontのトークンは、有効期限の30日前・7日前・1日前にアカウント設定のメールアドレスへ通知メールが送信される。

注意: APIのセキュリティ設定を変更すると、既存の発行済みトークンが無効化される（変更時に確認アラートが表示される）。稼働中のクライアントがある場合はトークンの再発行・差し替えを事前に計画すること。

1. Cookie認証（Webアプリ推奨）

セッションベースの認証。credentials: 'include' が必須。

// ログイン
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/login', {
  method: 'POST',
  credentials: 'include',  // 必須
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})

// レスポンス例
// {
//   "grant_token": "xxxxx",
//   "status": 0,
//   "member_id": 123
// }

注意点:

• サードパーティCookie問題（Safari等でブロックされる）
• APIドメインとフロントエンドを**同一ドメイン（サブドメイン違い）**に設定が必要（ファーストパーティCookie化）
  • 例: api.example.com と www.example.com
• Cookie認証APIが複数ある場合、各API間で認証状態が共有される

2. トークン認証（モバイルアプリ推奨）

JWTベースの認証。ヘッダーにトークンを付与。

取得フローは2段階: まず login（Login::login_challenge）に email/password をPOSTして grant_token を取得し、次に token（Login::token）エンドポイントへ grant_token をPOSTして access_token / refresh_token に交換する。token エンドポイントに email/password を直接送ることはできない（受け付けるボディは初回発行時 { "grant_token": "..." }、再発行時 { "refresh_token": "..." } のみ）。

// 1. ログインして grant_token を取得
const loginResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})
const { grant_token } = await loginResponse.json()

// 2. grant_token をアクセストークンに交換
const tokenResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ grant_token })
})

const { access_token, refresh_token } = await tokenResponse.json()

// レスポンス例
// {
//   "access_token": {
//     "value": "eyJhbGciOiJS...",
//     "expiresAt": "2024-01-01T12:00:00+09:00"
//   },
//   "refresh_token": {
//     "value": "xxxxxx",
//     "expiresAt": "2024-01-08T12:00:00+09:00"
//   }
// }

// API呼び出し時
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/news', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': access_token.value
  }
})

前提条件: ユーザー1人以上、login_challenge + token エンドポイント必須。トークン認証APIが複数ある場合、各API間で認証状態は共有されない。

3. StaticToken認証（サーバー間通信）

固定トークンによるAPIアクセス制限。

const response = await fetch('https://example.g.kuroco.app/rcms-api/1/internal-api', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': 'your-static-token-here'
  }
})

設定場所: 管理画面 → API → セキュリティ → StaticToken

注意: 静的トークンはフロントエンドに組み込まれるとユーザーに見える。流出時のトークン更新を想定した運用が必要。

IPアドレス制限

管理画面: [API] → [セキュリティ] → [IPアドレス制限]

指定されたIPアドレスからのアクセスのみ許可します。

IPアドレスグループ: 定数機能で IPSETS_* を定義し、[[IPSETS_*]] で参照可能（../kuroco-docs/docs/faq-domain.md（is-it-possible-to-set-multiple-ip-addresses-at-once） 参照）。

CORS設定

管理画面: [API] → [セキュリティ] → [CORS]

CSRF対策: CORS + Content-Type: application/json でモダンブラウザでのCSRF攻撃を防御。ワイルドカードを使うと防御効果がなくなるため、必ず特定ドメインを指定すること。

変更反映の遅延: CORS設定変更後は CORS_MAX_AGE 分だけブラウザにキャッシュされる。即時反映にはブラウザキャッシュクリアまたは CORS_MAX_AGE を 0 に設定。

APIリクエスト制限

閲覧制限の優先順序

コンテンツ返却時の制限は以下の順序で評価されます（上位優先）:

1. API → IPアドレス制限（API全体）
2. エンドポイント → APIリクエスト制限（エンドポイント単位）
3. コンテンツ定義 → APIリクエスト制限
4. コンテンツカテゴリ → APIリクエスト制限
5. 個別コンテンツ → APIリクエスト制限

後処理によるレスポンス制限

管理画面: [API] → エンドポイント → [後処理]

APIレスポンスから不要なフィールドを除外し、公開情報を制御:

パフォーマンスTip: 出力許可リストは他の処理の前に配置するとSQLレベルで効果あり。

プラットフォームセキュリティ

Kurocoプラットフォームが提供するインフラレベルのセキュリティ:

• 通信: HTTPS完全暗号化、TLS証明書自動管理
• 防御: WAF、CDN、DDoS対策（オプションでFastly DDoS Protection）
• 認証連携: SAML/OAuth外部ログイン、クライアント証明書（オプション）
• 監査: アクセスログ、アプリケーションログ
• 認定: ISMS (ISO 27001)、ISMSクラウド (ISO 27017)、プライバシーマーク
• 診断: 毎日のコンテナ脆弱性スキャン、VADDY連携自動診断

Admin MCPによる設定変更

APIのセキュリティ設定は管理画面だけでなく、Admin MCP経由でも操作可能です。接続・認証は /kuroco-admin-mcp スキルを参照してください。

キャッシュ戦略

推奨設定

重要: コンテンツ・メンバー等のデータ更新時、キャッシュは自動クリアされます。クリアされる範囲はデータの種類ごとに決まっているため、下記を把握しておくとキャッシュ期間を長めに設定しても安全かどうかを判断しやすい。

Topicsのキャッシュクリア範囲

上記以外の操作では自動クリアされない。 プロキシ経由・取り込み用のカスタムSmarty処理など、標準のTopics API以外の経路でデータを更新する場合は自動クリアの対象外なので、Smartyプラグイン purge_cdn_cache でクリア範囲・タイミングを明示的に指定する（例: Favorite::insertの後処理でTopics::detailsのキャッシュを削除）。急ぎクリアしたい場合はエンドポイント一覧の「キャッシュクリアする」ボタンで手動クリアもできる。

出典: ../kuroco-docs/docs/reference-api-1.md（cache-clear-operation）

キャッシュヘッダー

レスポンスヘッダーで確認可能：

Cache-Control: max-age=86400

流量制限

無料利用ユーザーの制限

決済情報未登録のユーザーには以下の制限があります。クレジットカード登録済み、または請求書払いのユーザーは対象外です。

レスポンスヘッダー

x-rcms-ratelimit-limit: 100      # 制限数
x-rcms-ratelimit-remaining: 95   # 残りリクエスト数
x-rcms-ratelimit-reset: 60       # リセットまでの秒数

429エラー時の対応

const response = await fetch(url)

if (response.status === 429) {
  const resetTime = response.headers.get('x-rcms-ratelimit-reset')
  throw new Error(`流量制限超過。${resetTime}秒後に再試行してください`)
}

API呼び出しパターン

一覧取得（ページネーション付き）

async function fetchNewsList(page = 1, perPage = 10) {
  const params = new URLSearchParams({
    pageID: page,
    cnt: perPage
  })

  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "list": [...],
  //   "pageInfo": {
  //     "totalCnt": 100,
  //     "perPage": 10,
  //     "totalPageCnt": 10,
  //     "pageNo": 1
  //   }
  // }

  return data
}

フィルター検索

// filter パラメータで検索
const params = new URLSearchParams({
  filter: 'subject contains "重要"',
  order_query: 'ymd=DESC'
})
// カテゴリでの絞り込みは contents_type を使う（category_id というフィールドは無い）
// 例: filter: 'contents_type = 1'

const response = await fetch(
  `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
  { credentials: 'include' }
)

詳細取得

async function fetchNewsDetail(topicsId) {
  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/newsdetail/${topicsId}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "details": {
  //     "topics_id": 1,
  //     "subject": "タイトル",
  //     "contents": "<p>本文</p>",
  //     ...
  //   }
  // }

  return data.details
}

多言語サイトでの公開状態の一括取得

Topics::list / Topics::details のエンドポイントで langs_open_flg パラメータを有効にすると、各コンテンツに全設定言語の公開状態を示す langs_open_flg オブジェクトが含まれます。言語ごとに個別のAPIリクエストを行わずに言語切替UIの表示制御が可能です。

// レスポンス例
// {
//   "details": {
//     "topics_id": 1,
//     "langs_open_flg": { "en": 1, "ja": 0 },
//     ...
//   }
// }

お気に入り日時の取得・並べ替え

Topics::list のエンドポイントで get_last_favorite_ymdhi パラメータを有効にすると、各コンテンツが最後にお気に入りされた日時（last_favorite_ymdhi）を取得できます。last_favorite_ymdhi での並べ替えにも対応しており、「人気順（最近お気に入りされた順）」の一覧表示が可能です。

コンテンツ作成

async function createNews(newsData) {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/news/insert',
    {
      method: 'POST',
      credentials: 'include',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        subject: newsData.title,
        contents: newsData.body,
        ymd: newsData.date,
        open_flg: 1  // 1: 公開, 0: 非公開（topics_flg は「一覧に載せる/載せない」の別フラグ）
      })
    }
  )

  return response.json()
}

エラーハンドリング

主要エラーコード

エラーレスポンス例

{
  "errors": [
    {
      "code": "authentication_error",
      "message": "ログインが必要です"
    }
  ]
}

エラーハンドリング実装

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    credentials: 'include',
    ...options
  })

  if (!response.ok) {
    const errorData = await response.json()

    switch (response.status) {
      case 401:
        throw new Error('認証が必要です')
      case 403:
        throw new Error('アクセス権限がありません')
      case 429:
        throw new Error('リクエスト制限を超えました')
      default:
        throw new Error(errorData.errors?.[0]?.message || 'APIエラー')
    }
  }

  return response.json()
}

Part 2: コンテンツ管理パターン

コンテンツ構造

階層構造

コンテンツ定義（TopicsGroup）
├── カテゴリ（TopicsCategory）
│   └── コンテンツ（Topics）
└── 拡張項目（ext_col_01〜ext_col_XX）

コンテンツ定義の設定

管理画面: [コンテンツ定義] → [新規作成]

拡張項目（カスタムフィールド）

キー名を推測しない。 拡張項目のキー名はサイト単位で ext_1 形式と ext_col_01 形式に分かれます。 Admin MCP に接続できる場合は whoami の site.topics_ext_key_format でそのサイトの命名を確認し、 どの番号がどの項目かは topics-describe（グループ単位の正）で確定させてください（→ /kuroco-admin-mcp）。 ext_slug を設定した項目はスラッグがキーになるため、この分岐の影響を受けません。設定を推奨します。 以下の表は ext_col_01 形式のサイトでの例です。

Topics API オペレーション

コンテンツCRUD操作

一覧取得レスポンス

{
  "list": [
    {
      "topics_id": 1,
      "subject": "タイトル",
      "contents": "本文（HTML）",
      "ymd": "2024-01-01",
      "open_flg": 1,
      "contents_type": 1,
      "contents_type_nm": "カテゴリ名",
      "ext_col_01": "拡張項目値",
      "tag": ["タグ1", "タグ2"]
    }
  ],
  "pageInfo": {
    "totalCnt": 100,
    "perPage": 10,
    "totalPageCnt": 10,
    "pageNo": 1
  }
}

コンテンツ作成

const response = await fetch('/rcms-api/1/news/insert', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: 'タイトル',
    contents: '<p>本文</p>',
    ymd: '2024-01-01',
    open_flg: 1,                          // 1: 公開, 0: 非公開
    contents_type: 1,                     // カテゴリID（category_idというフィールドは無い）
    open_type: 'sitei',                   // 予約公開を使う場合は 'sitei' を明示（既定 'open' のままだと日時が保存されない）
    open_sta_date: '2024-12-01 00:00:00', // 公開開始日時
    open_end_date: '2024-12-31 23:59:59', // 公開終了日時
    tag: ['タグ1', 'タグ2'],
    ext_col_01: 'カスタム値'
  })
})

コンテンツ更新

const response = await fetch(`/rcms-api/1/news/update/${topicsId}`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: '更新タイトル',
    contents: '更新本文'
    // 更新したいフィールドのみ送信可能
  })
})

コンテンツ削除

await fetch(`/rcms-api/1/news/delete/${topicsId}`, {
  method: 'POST',
  credentials: 'include'
})

フィルタークエリ

基本構文: filter={field} {operator} {value}

文字列の値は二重引用符で囲む。 シングルクォートは引用符ごと値の一部として扱われ、 エラーにならず0件になる（値に空白を含む場合は構文エラー）。

カテゴリのフィールド名は contents_type（category_id というフィールドは存在しない）。

複合条件: filter=(contents_type = 1 or contents_type = 2) and topics_flg = 1

ソート: order_query=ymd=DESC（{フィールド}={ASC|DESC}。複数指定はカンマ区切り）

詳細な使い方: references/filter-query.md を参照

ファイル・CSV操作

ファイルアップロード

// 1. ファイルアップロード
const formData = new FormData()
formData.append('file', file)
const result = await fetch('/rcms-api/1/files/upload', {
  method: 'POST',
  credentials: 'include',
  body: formData
})
const { file_id } = await result.json()

// 2. コンテンツに紐付け
await fetch('/rcms-api/1/news/insert', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: 'タイトル',
    ext_col_02: { file_id, desc: '説明' }
  })
})

詳細（一括更新、カテゴリ、タグ、閲覧制限）: references/file-operations.md を参照

Admin MCPによる管理操作（コンテンツ）

AIエージェント（Claude Desktop / claude.ai / Claude Code 等のMCPクライアント）から管理画面と同等のコンテンツ操作を行うには Admin MCP（/kuroco-admin-mcp スキル） を使用します。フロントエンドAPI（rcms-api）との違いに注意してください。

フロントエンドAPI vs 管理操作（Admin MCP）

活用シーン

• サイト構造の把握: コンテンツ定義一覧・拡張項目の確認
• データの一括確認・修正: 管理画面GUIを経由せず効率的にデータ操作
• スキーマ確認: Admin MCP のスキーマ取得ツールでフィールド定義を取得

注意: insert/update/deleteは必ずユーザーに確認してから実行すること。接続設定・ツールの詳細は /kuroco-admin-mcp スキル参照。

ベストプラクティス

• キャッシュ活用: エンドポイント設定で キャッシュ: 86400（1日）を設定。更新時は自動クリア
• ページネーション: pageID と cnt パラメータで分割取得

関連スキル

• /kuroco-frontend-integration - Vite/Nuxt.js/Next.jsでのAPI呼び出しパターン、KurocoFrontデプロイ
• /kuroco-server-processing - Smartyプラグイン・構文リファレンス、Webhook・バッチ処理
• /kuroco-admin-mcp - Admin MCP経由の管理操作

関連ドキュメント

スキル内リファレンス

• references/security-settings.md - セキュリティ設定の詳細リファレンス
• references/filter-query.md - フィルタークエリ詳細
• references/file-operations.md - ファイル・CSV操作詳細

Kuroco公式ドキュメント

• ../kuroco-docs/docs/management-api.md（api-security） - APIセキュリティ設定（認証方式、IP制限）
• ../kuroco-docs/docs/management-api.md（api-list） - API一覧・CORS設定
• ../kuroco-docs/docs/management-api.md（api-postprocessing） - API後処理の設定
• ../kuroco-docs/docs/reference-api-2.md（endpoint-settings） - エンドポイント設定項目一覧
• ../kuroco-docs/docs/reference-smarty-trigger-1.md（post-processing） - 後処理の詳細リファレンス
• ../kuroco-docs/docs/tutorials-api-custom-1.md（configure-endpoint） - エンドポイント設定方法
• ../kuroco-docs/docs/tutorials-auth-member-3.md（login） - ログイン実装
• ../kuroco-docs/docs/tutorials-api-custom-1.md（restricting-api-access-with-statictoken） - StaticToken認証
• ../kuroco-docs/docs/reference-api-1.md（api-cache） - APIキャッシュ
• ../kuroco-docs/docs/reference-api-1.md（cache-clear-operation） - APIキャッシュクリアのタイミングと範囲
• ../kuroco-docs/docs/reference-api-3.md（filter-query） - フィルタークエリ
• ../kuroco-docs/docs/about.md（security） - プラットフォームセキュリティ概要
• ../kuroco-docs/docs/faq-member.md（in-what-order-are-viewing-restrictions-applied） - 閲覧制限の優先順序
• https://kuroco.app/ja/docs/faq/cors-and-content-type-prevent-csrf-attacks/ - CSRF対策
• ../kuroco-docs/docs/faq-api-error.md（the-api-returns-403-forbidden-even-though-no-restrictions-are-applied） - 403エラーの解決
• ../kuroco-docs/docs/tutorials-content-1.md（adding-a-topics） - コンテンツ定義作成
• ../kuroco-docs/docs/tutorials-content-1.md（bulk-upload-in-csv） - CSVアップロード
• ../kuroco-docs/docs/management-content.md（content-structure-topics） - コンテンツ構造