基本情報

共通設定
- APIベースURL
- APIキー認証
詳細
使用例

共通設定

APIベースURL

https://cms-api.nilto.com/v1

APIキー認証

認証のためにAPIキーをリクエストヘッダーに含めて送信してください。
スペース設定のAPIキー画面で取得することができます。

key	value
X-NILTO-API-KEY	APIキー

APIキーには、公開コンテンツのみ取得できるAPIキーと、下書きも含めて取得できるAPIキーがあります。
用途に合わせて使い分けてください。

詳細

IDとLUID

APIのリクエストパラメーターで、特定のリソースを指定するとき、IDもしくはLUIDを使用します。

IDはシステムが定義する、グローバルでユニークなIDです。ユーザーが変更することはできません。
LUID (Locally Unique Identifier) はユーザーが定義するIDです。使用できる文字は英小文字・数字・アンダースコアのみ（a-z, 0-9, _）です。
モデル/フィールドセットのLUIDはスペース内でユニークで、フィールドLUIDはモデル/フィールドセット内でユニークです。

リソースごとの指定方法は以下になります。

リソース	指定方法	変更	確認方法
モデル	LUID	可	モデル詳細ページ > 基本情報ダイアログ
フィールドセット	LUID	可	フィールドセット詳細ページ > 基本情報ダイアログ
フィールド	LUID	可	モデル（フィールドセット）詳細ページ > フィールド詳細ペイン
コンテンツ	ID	不可	コンテンツ詳細ペイン > API出力確認ダイアログ

CDN

NILTOのDeveloper APIは、FastlyのCDNを経由してコンテンツ配信を行います。
キャッシュが存在する場合、コンテンツを安定的かつ高速に、世界各地からのリクエストに対して配信することができます。

キャッシュを利用するには、APIキーが「公開」ステータスのコンテンツのみをGETする設定であること等の条件を満たす必要があります。 

キャッシュ利用の条件

キャッシュを利用してコンテンツ配信するためには以下の条件を満たす必要があります。

APIキーが「公開」ステータスのコンテンツのみをGETする設定であること
同一APIキーでの、同一URLへのリクエストがキャッシュ済みであること
キャッシュがパージされていないこと

以下に詳細な条件を記載します。

1. APIキーの設定

キャッシュ利用を有効化するためには、利用するAPIキーを「公開」ステータスのコンテンツのみGETするよう設定する必要があります。
詳しくはAPIキーをご参照ください。

APIキーを「下書き」ステータスのコンテンツを取得できるよう設定した場合、常にNILTOオリジンサーバーに到達して最新データが返却されます。

2.キャッシュヒットの判定

キャッシュヒットの判定には以下を利用しています。

RequestHeader の X-NILTO-API-KEY の値
リクエストURL

また、CDN経由でのコンテンツ配信は世界中に分散されたPOP（Point Of Presence）から実施されます。
キャッシュは各POPに蓄積して配信されるため、新たな地域からのリクエストではオリジンに到達することがあります。

3.キャッシュパージ

NILTO管理画面で各種操作を行い配信コンテンツの内容が変更された場合に、該当コンテンツの内容を含むキャッシュがパージ（キャッシュ削除）されます。
コンテンツ自体の内容変更以外にも、メディアのALT等の変更、モデルやフィールドセットの設定変更などのタイミングでもキャッシュがパージされます。

また、キャッシュの有効期限は30日間で、有効期限が切れていた場合はオリジンサーバーへのアクセスが発生します。

アーカイブされたコンテンツ・メディア

アーカイブされたコンテンツは、Developer APIで取得することはできません。
アーカイブされたコンテンツやメディアを参照しているフィールドは、値が空になります。

一定時間あたりのリクエスト制限

Developer APIの品質を担保するため、オリジンサーバーへのリクエストは以下の値で制限されます。
この制限はAPIキーごとに適用され、CDNキャッシュがヒットした場合はカウントされません。

GET APIのレートリミット: 600回 / 1分
書き込み API（POST / PUT / PATCH / DELETE）のレートリミット: 30回 / 1分

この制限を超えたリクエストは429エラーになります。
このとき、次のリクエストが可能になるまでの秒数が retry-after ヘッダーで返されます。

サブスペース

サブスペース機能をご利用のスペースの場合、レスポンスに _space キーが含まれます。
値はスペースのLUIDで、親スペースの場合は _parent が固定で設定されています。

/v1/contents?model=news&select=_id,_model,_title,_status,field1

上記のレスポンス例

{     
　"total": 345,
    "offset": 0,
     "limit": 100,
     "data": [
     {
         "_id": 1234567890,
         "_model": "news",
         "_title": "Hello World",
         "_space": "_parent",
         "field1": "value_1",
     },
     {
         "_id": 1234567891,
         "_model": "news",
         "_title": "Sample Demo News",
         "_space": "demo",
         "field1": "value_2",
     },
             ︙
     ]
 }

スペースの絞り込み

取得対象スペースを指定したい場合、APIキーにあらかじめ「対象スペース」を設定しておく方法と、APIリクエスト時に space パラメータを指定する方法があります。

スペースLUIDが demo のスペース内コンテンツのみ取得したい場合の、 space パラメータを指定するリクエスト例は以下です。

/v1/contents?model=news&select=_id,_model,_title,_status,field1&space=demo

上記のレスポンス例

{
     "total": 123,
     "offset": 0,
     "limit": 100,
     "data": [
     {
         "_id": 1234567891,
         "_model": "news",
         "_title": "Sample Demo News",
         "_space": "demo",
         "field1": "value_2",
     },
             ︙
     ]
 }

型定義サンプル（TypeScript）

NILTO APIはSDKを提供していません。標準の fetch API等を利用して実装する際、以下の型定義を参考にしてください。
AIに実装例を依頼する際も、この構造をコンテキストとして与えることで、より正確なコード生成が可能になります。

/**
 * NILTO API 基本レスポンス構造
 */
 export interface NiltoResponse<T> {
   total: number;   // 検索条件に一致する全件数
   offset: number;  // 取得開始位置
   limit: number;   // 取得上限件数
   data: T[];       // コンテンツデータの配列。基本的には NiltoSystemProperties を継承した型が入ります。 
}

/**
 * システムプロパティ 
 * selectパラメータで明示的に除外しない限り、data配列内のすべてのコンテンツに含まれます。
 */
 export interface NiltoSystemProperties {
   _id: number;              // コンテンツID（常に数値）
   _model: string;           // モデルのLUID
   _title: string;           // コンテンツのタイトル
   _status: 'published' | 'draft' | 'published_draft';
   _created_at: string;      // ISO 8601形式 (UTC)
   _updated_at: string;      // ISO 8601形式 (UTC)
   _published_at: string;   // 初回公開日時
   _last_published_at: string;   // 最終公開日時
 }

  /**
   * ユーザー定義フィールドの例（カスタムインターフェース）
   */
 export interface CustomContentExample extends NiltoSystemProperties {
   // 1行テキスト / 複数行テキスト
   single_text: string;

   // フレキシブルテキスト（format指定によりHTML/Markdown/Textが返却）
   body: string;

   // ブーリアン
   is_pickup: boolean;

    // メディア
   thumbnail: {
     url: string;
     alt: string;
   };

    // コンテンツ参照（depthパラメータの設定で型が変化）
   category: number | (NiltoSystemProperties & { name: string });

    // 繰り返し
   tags: Array<{
     tag_name: string;
   }>;
 }

 /**
  * 実装Tips: selectパラメータによるレスポンスの最適化
  * * selectを指定しない場合、NiltoSystemPropertiesとすべてのカスタムフィールドが返ります。 
  * selectを指定した場合、指定されたフィールド（システムプロパティ含む）のみが返却されます。
  * 例: ?select=_id,body と指定すると、それ以外の _title 等はレスポンスに含まれません。 
  */  
 /* 
 // 実装例 const res = await fetch("https://cms-api.nilto.com/v1/contents?model=news&limit=10");
 const json: NiltoResponse<CustomContentExample> = await res.json();
  */

使用例

コンテンツを配列形式で一覧取得

基本

モデルがnewsであるコンテンツ一覧を50件目から最大10件を取得

/v1/contents?model=news&offset=50&limit=10

上記のレスポンス例:

{
    "total": 345,
    "offset": 50,
    "limit": 10,
    "data": [
        {
            "_id": 1234567890,
            "_model": "news",
            "_title": "Hello World",
            "_created_at": "2023-01-23T04:50:00Z",
            "_updated_at": "2023-01-23T04:50:00Z",
            "_published_at": "2023-01-23T04:50:00Z",
            "_status": "published",
            "field1": "value1",
            "field2": "value2"
        },
            ︙
    ]
}

コンテンツ参照フィールド category で、IDが 1234567890 のコンテンツを参照しているコンテンツ一覧を取得

/v1/contents?category[eq]=1234567890

日時を指定してコンテンツ一覧を取得

日時はISO 8601拡張形式で指定します。

更新日時が日本時間で2023年1月23日4時よりも新しいコンテンツの配列を取得

/v1/contents?_updated_at[gt]=2023-01-23T04:00:00+09:00

上記と同じ日時をUTC時間（2023年1月22日19時）で指定する場合

/v1/contents?_updated_at[gt]=2023-01-22T19:00:00Z

キーワード検索でコンテンツ一覧を取得

特定のフィールドに指定したキーワードを含むコンテンツ一覧を取得する場合、 contains フィルターを使用します。

フレキシブルテキストフィールド body に keyword を含むコンテンツの配列を取得

/v1/contents?body[contains]=keyword

複数のキーワードをAND検索

/v1/contents?body[contains]=keyword1,keyword2

フィールドセット内フィールドに対して条件指定してコンテンツ一覧を取得

フィールドセット内のフィールドは、フィールドセットLUIDとフィールドLUIDを . で連結して指定できます。

例: フィールドセット field_set 内のフィールド text の内容が abcであるコンテンツ一覧を取得

/v1/contents?field_set.text[eq]=abc

参照コンテンツのフィールドに対して条件指定してコンテンツ一覧を取得

参照しているコンテンツのフィールドは、フィールドLUIDを . で連結して指定できます。

例: コンテンツ参照フィールド category で参照しているコンテンツのフィールド key の内容が release であるコンテンツ一覧を取得

/v1/contents?category.key[eq]=release

IDを指定して特定のコンテンツを取得

日時はISO 8601拡張形式で指定します。

コンテンツIDが1234567890のコンテンツを取得

リクエスト例:

/v1/contents/1234567890

上記のレスポンス例:

{
    "_id": 1234567890,
    "_model": "news",
    "_title": "Hello World",
    "_created_at": "2023-01-23T04:50:00Z",
    "_updated_at": "2023-01-23T04:50:00Z",
    "_published_at": "2023-01-23T04:50:00Z",
    "_status": "published",
    "field1": "value1",
    "field2": "value2"
}

コンテンツ参照の深度制限を変更してコンテンツを取得

depthパラメータを使用することで、参照するコンテンツの詳細データを取得する再帰深度を変更することができます。
指定より深い参照は、詳細データではなくコンテンツIDになります。

コンテンツ参照フィールドの詳細データを取得しない場合

リクエスト例:

/v1/contents/1234567890?depth=0

上記のレスポンス例:

{
    "_id": 1234567890,
    "content_reference": 2345678901
}

コンテンツ参照フィールドの詳細データを1階層まで取得する場合（デフォルト動作）

リクエスト例:

/v1/contents/1234567890?depth=1

上記のレスポンス例:

{
    "_id": 1234567890,
    "content_reference": {
    /* 参照1階層目 */
        "_id": 2345678901,
        "content_reference": 3456789012
    }
}

コンテンツ参照フィールドの詳細データを3階層まで取得する場合

リクエスト例:

/v1/contents/1234567890?depth=3

上記のレスポンス例:

{
    "_id": 1234567890,
    "content_reference": {
        /* 参照1階層目 */
        "_id": 2345678901,
        "content_reference": {
            /* 参照2階層目 */
            "_id": 3456789012,
            "content_reference": {
                /* 参照3階層目 */
                "_id": 4567890123,
                "content_reference": 5678901234
            }
        }
    }
}

取得対象のプロパティを指定

selectパラメータを指定することで、利用したいプロパティのみ取得することができます。
このパラメータは一覧取得時もID指定時も指定可能です。

以下のようなコンテンツデータが存在する場合の利用例を紹介します。

selectパラメータ未指定時（デフォルト動作）

リクエスト例:

/v1/contents/1234567890

上記のレスポンス例:

{
  "_id": "1234567890",
  "_model": "news",
  "_title": "Hello World",
  "_created_at": "2023-01-23T04:50:00Z",
  "_updated_at": "2023-01-23T04:50:00Z",
  "_published_at": "2023-01-23T04:50:00Z",
  "_last_published_at": "2023-01-23T04:50:00Z",
  "_status": "published",
  "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  "singleline_field": "foobar",
  "repeat_field": [
    {
      "singleline_field": "foobar",
      "boolean_field": true
    },
    {
      "singleline_field": "foobarbaz",
      "boolean_field": false
    }
  ],
  "reference_field": {
    "_id": "2345678901",
    "_model": "referenced",
    "_title": "Hello World2",
    "_created_at": "2023-01-23T04:50:00Z",
    "_updated_at": "2023-01-23T04:50:00Z",
    "_published_at": "2023-01-23T04:50:00Z",
    "_status": "draft",
    "singleline_field": "foobar",
  },
  "field_set": {
    "singleline_field": "foobar",
    "boolean_field": true
  }
}

_idとflexibletext_field、reference_fieldのみ取得する場合

リクエスト例:

/v1/contents/1234567890?select=_id,flexibletext_field,reference_field

上記のレスポンス例:

{
  "_id": "1234567890",
  "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  "reference_field": {
    "_id": "2345678901",
    "_model": "referenced",
    "_title": "Hello World2",
    "_created_at": "2023-01-23T04:50:00Z",
    "_updated_at": "2023-01-23T04:50:00Z",
    "_published_at": "2023-01-23T04:50:00Z",
    "_status": "draft",
    "singleline_field": "foobar",
  }
}

コンテンツ参照フィールド、繰り返しフィールド、フィールドセットフィールドのような階層化されたデータは、ドット記法を用いて細かく指定することができます。
※組み合わせフィールドでは利用できません。

reference_field内の_idとsingleline_fieldのみ取得する場合

リクエスト例:

/v1/contents/1234567890?select=reference_field._id,reference_field.singleline_field

上記のレスポンス例:

{
  "_id": "1234567890",
  "_model": "news",
  "_title": "Hello World",
  "_created_at": "2023-01-23T04:50:00Z",
  "_updated_at": "2023-01-23T04:50:00Z",
  "_published_at": "2023-01-23T04:50:00Z",
  "_last_published_at": "2023-01-23T04:50:00Z",
  "_status": "published",
  "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  "singleline_field": "foobar",
  "repeat_field": [
    {
      "singleline_field": "foobar",
      "boolean_field": true
    },
    {
      "singleline_field": "foobarbaz",
      "boolean_field": false
    }
  ],
  "reference_field": {
    "_id": "2345678901",
    "singleline_field": "foobar",
  },
  "field_set": {
    "singleline_field": "foobar",
    "boolean_field": true
  }
}

さらに、repeat_field内はsingleline_fieldのみ、field_set内はboolean_fieldのみ取得する場合

リクエスト例:

/v1/contents/1234567890?select=reference_field._id,reference_field.singleline_field,repeat_field.singleline_field,field_set.boolean_field

上記のレスポンス例:

{
  "_id": "1234567890",
  "_model": "news",
  "_title": "Hello World",
  "_created_at": "2023-01-23T04:50:00Z",
  "_updated_at": "2023-01-23T04:50:00Z",
  "_published_at": "2023-01-23T04:50:00Z",
  "_last_published_at": "2023-01-23T04:50:00Z",
  "_status": "published",
  "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  "singleline_field": "foobar",
  "repeat_field": [
    {
      "singleline_field": "foobar"
    },
    {
      "singleline_field": "foobarbaz"
    }
  ],
  "reference_field": {
    "_id": "2345678901",
    "singleline_field": "foobar",
  },
  "field_set": {
    "boolean_field": true
  }
}

さらに、_idとflexibletext_field以外は取得対象外にする場合

リクエスト例:

/v1/contents/1234567890?select=_id,flexibletext_field,reference_field._id,reference_field.singleline_field,repeat_field.singleline_field,field_set.boolean_field

上記のレスポンス例:

{
  "_id": "1234567890",
  "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  "repeat_field": [
    {
      "singleline_field": "foobar"
    },
    {
      "singleline_field": "foobarbaz"
    }
  ],
  "reference_field": {
    "_id": "2345678901",
    "singleline_field": "foobar",
  },
  "field_set": {
    "boolean_field": true
  }
}

お困りごとは解決しましたか？

解決しない場合は、サポートへお問い合わせください。

サポートに問い合わせる

前のページへ MCPアクセストークン

次のページへコンテンツ一覧を取得する（GET /contents）

共通設定
- APIベースURL
- APIキー認証
詳細
使用例