kuroco-content-management

Kuroco Content Management Patterns

Best practices for content management (create, retrieve, update, delete) in Kuroco HeadlessCMS.

Documentation Reference: /kuroco-docs You can search and reference the official Kuroco documentation using the skill.

Content Structure
Extended Fields (Custom Fields)
Topics API Operations
Content CRUD Operations
Filter Query → For details, see references/filter-query.md
File and CSV Operations → For details, see references/file-operations.md
Content Operations via the Management API (mng_api)

Content Structure

Hierarchical Structure

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

Content Definition Settings

Admin panel: [Content Definition] → [Create New]

Item	Description
Group Name	Name of the content definition
Identifier	Unique ID (alphanumeric)
Body Input Method	WYSIWYG, Markdown, HTML
Viewing Restriction	Everyone/Group Restriction/Custom Search
Editing Restriction	Everyone/Group Restriction/Custom Search
Extended Fields	Custom fields (up to 99)

Extended Fields (Custom Fields)

Type	Description	API Response Example
Text	Single-line text	`"ext_col_01": "値"`
Textarea	Multi-line text	`"ext_col_02": "複数行\nテキスト"`
WYSIWYG	Rich Text	`"ext_col_03": "<p>HTML</p>"`
Numeric	Integer/Decimal	`"ext_col_04": 100`
Date	Date selection	`"ext_col_05": "2024-01-01"`
Select (single)	Radio Button	`"ext_col_06": "選択肢1"`
Select (multiple)	Checkbox	`"ext_col_07": ["選択肢1", "選択肢2"]`
File/Image	Upload	`"ext_col_08": { "id": "xxx", "url": "https://...", "desc": "" }`
Link	URL Link	`"ext_col_10": { "url": "https://...", "title": "リンク名" }`
Related Content	Reference to other content	`"ext_col_11": { "topics_id": 123, "subject": "タイトル" }`

Topics API Operations

Operation	Description	Method	Path Example
list	List Retrieval	GET	`/news`
details	Detail Retrieval	GET	`/newsdetail/{topics_id}`
insert	Add New	POST	`/news/insert`
update	Update	POST	`/news/update/{topics_id}`
delete	Delete	POST	`/news/delete/{topics_id}`
bulk_upsert	Bulk Update	POST	`/news/bulk`

Content CRUD Operations

List Retrieval Response

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

Content Creation

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',
    topics_flg: 1,           // 1: 公開, 0: 非公開
    category_id: 1,
    open_ymd: '2024-12-01',  // 予約公開開始日
    close_ymd: '2024-12-31', // 公開終了日
    tag: ['タグ1', 'タグ2'],
    ext_col_01: 'カスタム値'
  })
})

Content Update

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

Content Deletion

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

Filter Query

Basic Syntax: filter={field} {operator} {value}

Operator	Example
`=`, `!=`	`filter=category_id = 1`
`>`, `>=`, `<`, `<=`	`filter=ymd >= '2024-01-01'`
`contains`	`filter=subject contains 'キーワード'`
`in`, `not_in`	`filter=category_id in [1, 2, 3]`

Compound Conditions: filter=(category_id = 1 or category_id = 2) and topics_flg = 1

Sort: order_by=ymd desc

Detailed Usage: references/filter-query.md See

File and CSV Operations

File Upload

// 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: '説明' }
  })
})

Details (Bulk Update, Categories, Tags, Viewing Restrictions): references/file-operations.md See

Content Operations via the Management API (mng_api)

/kuroco-mng-api-browser By using the skill, you can perform content operations equivalent to those in the admin screen via the browser. Note the difference from the frontend API (rcms-api).

Frontend API vs Admin API

Item	Frontend API (rcms-api)	Admin API (mng_api)
Target	End User	Administrators/Operators
Authentication	StaticToken / DynamicToken / Cookie	Admin screen session cookie
Endpoint	`/rcms-api/{api_id}/{path}`	`/direct/rcms_api/mng_api/`
Use case	Frontend implementation	Bulk data operations, structure checks, configuration changes

Get content definition list

// mng_api: コンテンツ定義（TopicsGroup）一覧（columnsで必要カラムのみ取得）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_group_list&columns=topics_group_id,group_nm', {credentials:'include'});
const data = await r.json();
JSON.stringify(data.topics_group_list?.map(g => ({id: g.topics_group_id, name: g.group_nm})));

Get content list

// mng_api: 特定コンテンツ定義のコンテンツ一覧（columnsで必要カラムのみ取得）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_list&topics_group_id[]=1&cnt=10&columns=topics_id,subject,ymd', {credentials:'include'});
const data = await r.json();
JSON.stringify(data.topics_list?.map(t => ({id: t.topics_id, subject: t.subject, ymd: t.ymd})));

Create content

// mng_api: コンテンツ作成（※実行前にユーザー確認必須）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_edit', {
  method: 'POST',
  credentials: 'include',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: 'タイトル',
    contents: '本文',
    topics_group_id: 1,
    topics_flg: 1
  })
});
const data = await r.json();
JSON.stringify({id: data.topics_id});

Usage scenarios

Understanding site structure: Check content definition list and extended items
Bulk checking/correcting data: Efficiently operate data without going through the admin screen GUI
Schema check: MODE=schema&mt=topics&ct=topics_list Get field definitions with

Note: Always confirm with the user before executing insert/update/delete. For details, see /kuroco-mng-api-browser skill reference.

Best Practices

Cache usage: In the endpoint settings, set キャッシュ: 86400(1 day). Automatically cleared on update
Pagination: pageID と cnt Retrieve in chunks using the parameter

Related skills

/kuroco-api-integration - API design/authentication patterns
/kuroco-mng-api-browser - Content operations via the admin API (via browser)
/kuroco-smarty-plugins - Content operations in Smarty templates (assign_topics_list, etc.)
/kuroco-webhook-processing - Automatic content processing in batch processing

About this skill

Table of Contents