APIリファレンス
コンテンツAPI

コンテンツAPI

TWPのコンテンツ管理システムで作成したコンテンツを取得・検索するAPIです。

ユースケース

  • コーポレートサイトのニュース・お知らせ表示
  • ブログ・メディアサイトの記事表示
  • ヘッドレスCMSとしての利用

エンドポイント一覧

メソッドパス説明
GET/v1/cms/contentsコンテンツ一覧取得
GET/v1/cms/contents/{id}コンテンツ詳細取得（ID指定）
GET/v1/cms/contents/slug/{slug}コンテンツ詳細取得（スラッグ指定）
GET/v1/cms/categoriesカテゴリ一覧取得
GET/v1/cms/categories/{id}カテゴリ詳細取得
POST/v1/cms/searchコンテンツ検索

コンテンツ一覧取得

GET /v1/cms/contents

公開済みコンテンツの一覧を取得します。

パラメータ

パラメータ型必須説明
category_codestring△カテゴリコードで絞り込み
category_idstring△カテゴリIDで絞り込み
tagsstring-タグで絞り込み（カンマ区切りでAND検索）
tag_idsstring-タグIDで絞り込み（カンマ区切りでAND検索）
field_filtersstring-カスタムフィールドで絞り込み
sortstring-ソート順（例: published_at:desc）
limitnumber-取得件数（1〜100、デフォルト: 20）
cursorstring-ページネーションカーソル

※ category_code または category_id のいずれかを指定することを推奨します。

リクエスト例

curl -X GET "https://your-tenant.api.tocca.systems/v1/cms/contents?category_code=news&limit=10" \
  -H "X-API-Key: your_api_key"

レスポンス例

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "新サービスのお知らせ",
      "slug": "new-service-announcement",
      "category_id": "cat-001",
      "category_code": "news",
      "category_name": "ニュース",
      "published_at": "2024-01-15T10:00:00Z",
      "author_name": "管理者",
      "tags": ["重要", "サービス"],
      "summary": "新しいサービスを開始しました..."
    }
  ],
  "pagination": {
    "count": 10,
    "next_cursor": "eyJsYXN0X2lkIjoi...",
    "has_more": true
  }
}

カスタムフィールドでの絞り込み

カスタムフィールドで絞り込む場合は、field_filters パラメータを使用します。

field_filters=status:active,priority:high

フォーマット: フィールドID:値 をカンマ区切りで指定（最大3件）

コンテンツ詳細取得（ID指定）

GET /v1/cms/contents/{id}

パラメータ

パラメータ型必須説明
idstring○コンテンツID

レスポンス例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "新サービスのお知らせ",
  "slug": "new-service-announcement",
  "category_id": "cat-001",
  "category_code": "news",
  "category_name": "ニュース",
  "content": {
    "body": "<p>新しいサービスを開始しました。</p>",
    "summary": "新しいサービスを開始しました...",
    "custom_field_1": "カスタム値"
  },
  "published_at": "2024-01-15T10:00:00Z",
  "version": 3,
  "author_name": "管理者",
  "tags": ["重要", "サービス"],
  "meta": {
    "og_title": "新サービスのお知らせ",
    "og_description": "新しいサービスを開始しました"
  }
}

コンテンツ詳細取得（スラッグ指定）

GET /v1/cms/contents/slug/{slug}

URLフレンドリーなスラッグでコンテンツを取得します。

パラメータ

パラメータ型必須説明
slugstring○コンテンツのスラッグ

カテゴリ一覧取得

GET /v1/cms/categories

有効なカテゴリの一覧を取得します。

レスポンス例

{
  "items": [
    {
      "id": "cat-001",
      "code": "news",
      "name": "ニュース",
      "description": "会社からのお知らせ",
      "sort": 1
    },
    {
      "id": "cat-002",
      "code": "blog",
      "name": "ブログ",
      "description": "スタッフブログ",
      "sort": 2
    }
  ]
}

カテゴリ詳細取得

GET /v1/cms/categories/{id}

カテゴリの詳細情報（カスタムフィールド定義を含む）を取得します。

レスポンス例

{
  "id": "cat-001",
  "code": "news",
  "name": "ニュース",
  "description": "会社からのお知らせ",
  "fields": [
    {
      "id": "priority",
      "name": "優先度",
      "type": "select",
      "options": ["high", "medium", "low"]
    }
  ],
  "sort": 1
}

コンテンツ検索

POST /v1/cms/search

全文検索でコンテンツを検索します。

リクエストボディ

フィールド型必須説明
querystring○検索キーワード（最大500文字）
category_idstring-カテゴリIDで絞り込み
tagsstring[]-タグで絞り込み（OR検索）
sortstring-ソート順
fromnumber-オフセット（デフォルト: 0）
sizenumber-取得件数（1〜100、デフォルト: 20）
filterobject-カスタムフィールドフィルター

ソートオプション

値説明
relevance関連度順（デフォルト）
published_at:desc公開日時の降順（新しい順）
published_at:asc公開日時の昇順（古い順）
custom_{field}:ascカスタムフィールドの昇順
custom_{field}:descカスタムフィールドの降順

カスタムフィールドフィルター

{
  "query": "*",
  "filter": {
    "custom_status": "active",
    "custom_price": {
      "gte": 1000,
      "lte": 5000
    }
  }
}

使用可能な演算子:

  • eq: 完全一致（デフォルト）
  • gte: 以上
  • lte: 以下
  • gt: 超過
  • lt: 未満
  • in: 複数値のいずれか

リクエスト例

curl -X POST "https://your-tenant.api.tocca.systems/v1/cms/search" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "新サービス",
    "category_id": "cat-001",
    "sort": "published_at:desc",
    "size": 10
  }'

レスポンス例

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "新サービスのお知らせ",
      "slug": "new-service-announcement",
      "category_id": "cat-001",
      "published_at": "2024-01-15T10:00:00Z",
      "author_name": "管理者",
      "tags": ["重要"],
      "score": 12.5,
      "highlight": {
        "title": ["<em>新サービス</em>のお知らせ"],
        "search_text": ["...本日より<em>新サービス</em>を開始しました..."]
      },
      "custom_fields": {
        "custom_status": "active",
        "custom_price": 3000
      }
    }
  ],
  "pagination": {
    "total": 25,
    "from": 0,
    "size": 10,
    "has_more": true
  }
}

キャッシュについて

コンテンツ一覧・詳細取得APIのレスポンスは、60秒間キャッシュされます。リアルタイム性が必要な場合は、検索APIの使用を検討してください。

認証問い合わせAPI