kintone REST APIは、kintoneの外にあるプログラムからレコードを読んだり書いたりするための入口です。フォームや問い合わせの受け口、会計ソフト、チャット、スプレッドシートとkintoneをつなぐ仕組みは、ほとんどがこのAPIの上に乗っています。この記事では、APIトークンを発行し、curlで1件取得するところから始めて、登録・更新・削除、クエリの書き方、1万件を超える取得、エラーの読み方、回数の制限、Webhookでの外部連携まで通して書きます。アプリ管理権限があり、JSONを見たことがある人を前提にしています。
先に決めること
そもそも使える契約か
REST APIはスタンダードコースとワイドコースで使えます。ライトコースではAPIトークンもWebhookも使えません。料金はスタンダードが1ユーザー月額1,800円(税抜、10ユーザーから)、ワイドが3,000円(税抜、1,000ユーザーから)です。最初に契約を確かめます。
REST APIで何ができるか
APIの領域は、レコード(取得・登録・更新・削除・コメント・ステータス)、ファイル(アップロード・ダウンロード)、アプリ(フィールドや一覧、アクセス権などの設定)、スペース、プラグイン、API情報の6つです。実際の連携で使うのは、ほとんどがレコードとファイルです。
どの認証で動かすか
認証の方式は4つあります。外から動かす連携の多くはAPIトークンで足ります。
| 方式 | 指定のしかた | 向いている場面 |
|---|---|---|
| APIトークン認証 | X-Cybozu-API-Token ヘッダーにアプリで発行したトークン | 1つか少数のアプリを外から定期的に読み書きする |
| パスワード認証 | X-Cybozu-Authorization ヘッダーに「ログイン名:パスワード」をBase64にした値 | アプリをまたぐ処理、スペースの操作など、トークンで足りないとき |
| OAuth認証 | Authorization: Bearer にアクセストークン | 外部サービスに、使う人ごとの権限で操作させたいとき |
| セッション認証 | kintoneにログインしているブラウザーのセッション | kintoneの中で動かすJavaScriptから呼ぶとき |
APIトークンでの操作は、Administratorによる操作として扱われます。誰が登録したかを残したいなら、担当者のフィールドを別に用意します。2要素認証を有効にしたユーザーはパスワード認証でAPIを実行できないので、パスワード認証が要るなら連携専用のユーザーを作ります。
1日の回数から逆算する
1日に実行できるAPIリクエストは、1つのアプリにつきスタンダードコースで10,000件、ワイドコースで100,000件です。数え方の区切りは日本時間の9:00から翌日8:59までです。一方で、1回で取得できるレコードは500件まで、1回で登録・更新・削除できるのは100件までです。
5万件の顧客アプリを毎朝まるごと読むなら、500件ずつで100回です。1件ずつ取りに行くと5万回になり、上限を一瞬で使い切ります。作る前に「1日に何件動くか」と「1回に何件まとめられるか」を書き出します。
連携ごとにトークンを分ける
トークンは1アプリ20個まで発行できます。連携ごとに別のトークンにして、要る権限だけを付けます。使い回すと、漏れたときに全部の連携を止めることになります。
設計表
主なAPIと上限
URLはすべて https://(サブドメイン).cybozu.com/k/v1/ のあとに続けます。ゲストスペースのアプリは /k/guest/(スペースID)/v1/ になります。
| やりたいこと | メソッド | URLの末尾 | 1回の上限 |
|---|---|---|---|
| 1件取得 | GET | record.json | 1件 |
| 複数取得 | GET | records.json | 500件。offsetは10,000まで |
| 1件登録 | POST | record.json | 1件 |
| 複数登録 | POST | records.json | 100件 |
| 1件更新 | PUT | record.json | 1件 |
| 複数更新(UPSERTも) | PUT | records.json | 100件 |
| 複数削除 | DELETE | records.json | 100件 |
| カーソル作成・取得・削除 | POST・GET・DELETE | records/cursor.json | 1回500件。有効なカーソルは1ドメイン10個まで |
| ファイルのアップロード | POST | file.json | 1回1ファイル |
| ファイルのダウンロード | GET | file.json | 1ファイル |
| 複数のAPIをまとめて実行 | POST | bulkRequest.json | 20リクエスト |
複数登録・複数更新・複数削除は、1件でも失敗するとそのリクエストの全件が取り消されます。途中まで書き込まれて半端に残ることはありません。
全体の制限
| 項目 | 上限 |
|---|---|
| 同時接続 | 1ドメインにつき100。超えると429が返る |
| 1日のリクエスト数 | 1アプリにつきスタンダード10,000件、ワイド100,000件 |
| リクエストボディ | 50MBまで |
| 添付ファイル | 1ファイル1GBまで |
| アップロードしたファイル | レコードに添付しないと3日で削除 |
| APIトークン | 1アプリ20個まで。1回のリクエストで指定できるのは9個まで |
| Webhook | 1アプリ10個まで。通知はドメイン単位で1分60回まで |
ファイルのアップロード・ダウンロードなど、1日のリクエスト数に数えないAPIもあります。
作る手順
アプリIDを確かめる
アプリを開いたときのURLが https://example.cybozu.com/k/123/ なら、/k/ のあとの123がアプリIDです。この記事の例は、サブドメインをexample、アプリIDを123にしています。フィールドの指定にはフィールド名ではなくフィールドコードを使うので、フォームの設定で各フィールドのフィールドコードも控えておきます。
APIトークンを発行する
- レコードの一覧画面の右上にある歯車の「アプリを設定」をクリックします。
- 「設定」タブを開きます。
- 「カスタマイズ/サービス連携」の「APIトークン」をクリックします。
- 「生成する」をクリックします。
- 生成されたトークンの「アクセス権」で、許可する操作にチェックを入れます。
- 「メモ」の編集アイコンをクリックし、用途と担当者を書きます(200文字まで)。
- ✔の形の「保存」アイコンでメモを保存します。
- 画面右下の「保存」をクリックします。
- 画面右上の「アプリを更新」をクリックします。
- ダイアログで、もう一度「アプリを更新」をクリックします。
アクセス権は、生成した直後は「レコード閲覧」だけにチェックが入っています。取得だけの連携ならこのままにし、登録する連携なら追加、更新するなら編集、と要る操作だけを足します。トークンに付けたアクセス権は、アプリ・レコード・フィールドのアクセス権の設定より優先されます。トークンを持っている人は、画面では見られないはずのレコードやフィールドも読めるということです。
いちばん多い失敗は、手順8から10を飛ばすことです。トークンを作ってもアクセス権を変えても、アプリを更新するまでAPIには効きません。権限を足したのに動かないときは、まずアプリを更新したかを見ます。


1件取得してみる
Macならターミナル、WindowsならPowerShellで実行します。トークンの文字列は自分のものに置き換えます。
curl -X GET 'https://example.cybozu.com/k/v1/record.json?app=123&id=1' \
-H 'X-Cybozu-API-Token: ここにAPIトークン'
返ってくるのは次のような形のJSONです。
{
"record": {
"会社名": { "type": "SINGLE_LINE_TEXT", "value": "株式会社サンプル" },
"見込み金額": { "type": "NUMBER", "value": "300000" },
"$revision": { "type": "__REVISION__", "value": "3" }
}
}
フィールドコードごとに type と value が並びます。数値も文字列で返るので、計算する前に数値に直します。チェックボックスは文字列の配列、ユーザー選択は code と name の配列です。日時は 2026-10-01T00:30:00Z のように協定世界時で返るので、日本時間なら9時間足します。WindowsのPowerShellでは curl.exe と書き、行末の \ は ` “ に変えます。

レコードを登録する
curl -X POST 'https://example.cybozu.com/k/v1/record.json' \
-H 'X-Cybozu-API-Token: ここにAPIトークン' \
-H 'Content-Type: application/json' \
-d '{
"app": 123,
"record": {
"会社名": { "value": "株式会社サンプル" },
"受付日": { "value": "2026-10-22" }
}
}'
成功すると {"id":"101","revision":"1"} のように、採番されたレコードIDとリビジョンが返ります。
気をつけることは3つです。存在しないフィールドコードはエラーにならず無視されるので、1文字間違えるとその欄だけ空のまま成功します。登録した直後に画面で1件開いて確かめます。計算、カテゴリー、ステータス、作業者、ルックアップでコピーされるフィールドには書けません。日時は 2026-10-22T09:00:00+09:00 のように時差を付けて送ります。
ルックアップにはキーの値を送ります。コピー元のアプリのトークンも要るので、X-Cybozu-API-Token に登録先とコピー元のトークンをカンマ区切りで並べます(1回9個まで)。ルックアップの「コピー元のフィールド」は、レコード番号か「値の重複を禁止する」をオンにしたフィールドにしておきます。自動計算を設定した文字列(1行)をコピー元にしたルックアップは、APIで値を変えられません。
レコードを更新する
レコードIDを指定する形が基本です。
curl -X PUT 'https://example.cybozu.com/k/v1/record.json' \
-H 'X-Cybozu-API-Token: ここにAPIトークン' \
-H 'Content-Type: application/json' \
-d '{
"app": 123,
"id": 101,
"revision": 1,
"record": {
"対応状況": { "value": "対応中" }
}
}'
revision は、取得したときのリビジョンです。その間に誰かが画面で編集していればエラーになり、上書きされません。省略するか -1 なら確かめずに上書きします。人が画面でも触るアプリでは付けておきます。
外部の顧客番号でレコードを探して更新するなら、id の代わりに "updateKey": { "field": "顧客番号", "value": "C-0012" } を送ります。使えるのは「値の重複を禁止する」をオンにした文字列(1行)か数値だけです。あれば更新、なければ登録、をまとめたいときは、複数更新の records.json に "upsert": true を付けます。2025年1月に入った機能で、トークンには編集に加えて追加の権限も要ります。
テーブルは、一部の行だけを直すときも残す行を全部送ります。送らなかった行は消えます。行の id を付けた行は更新、付けない行は追加になります。
レコードを削除する
curl -X DELETE 'https://example.cybozu.com/k/v1/records.json' \
-H 'X-Cybozu-API-Token: ここにAPIトークン' \
-H 'Content-Type: application/json' \
-d '{ "app": 123, "ids": [101, 102] }'
削除したレコードは画面からも戻せません。削除の権限を付けたトークンは、本当に削除が要る連携にだけ発行します。
クエリで絞り込む
複数取得では query に条件を書きます。
| 演算子 | 意味 | 例 |
|---|---|---|
= != | 等しい、等しくない | 会社名 = "株式会社サンプル" |
> < >= <= | 大小 | 見込み金額 >= 100000 |
in not in | どれかに一致、どれにも一致しない | 対応状況 in ("未対応", "対応中") |
like not like | 含む、含まない | 会社名 like "サンプル" |
is empty is not empty | 空、空でない | 担当者名 is empty |
and or | 条件の組み合わせ | 受付日 = TODAY() and 担当 in (LOGINUSER()) |
日付には TODAY()、YESTERDAY()、THIS_MONTH()、LAST_MONTH()、FROM_TODAY(-7, DAYS) などの関数が使えます。並べ替えと件数は条件のあとに order by 受付日 desc limit 500 offset 0 の順で書きます。order by を省くとレコードIDの降順、limit を省くと100件です。
文字列の検索は単語検索なので、like は区切り方によって拾えないことがあります。テーブルの中と関連レコード一覧のフィールドは = が使えず、in で書きます。値に " や \ が入るときは \ を前に付けます。
curlでは、日本語や空白をURLエンコードして送ります。-G と --data-urlencode を使うと、curlがエンコードしてURLの後ろに付けてくれます。
curl -G 'https://example.cybozu.com/k/v1/records.json' \
-H 'X-Cybozu-API-Token: ここにAPIトークン' \
--data-urlencode 'app=123' \
--data-urlencode 'query=対応状況 in ("未対応") order by 受付日 desc limit 500' \
--data-urlencode 'fields[0]=会社名'
fields で要るフィールドだけに絞ると速くなります。URLが8KBを超えると「Request URL Too Large」で止まるので、そのときはPOSTに X-HTTP-Method-Override: GET ヘッダーを付けて送ります。
1万件を超えて取得する
offset は10,000までなので、offset をずらして取る書き方は1万件を超えたところで止まります。超える見込みがあるなら、最初から次のどちらかで書きます。
1つ目はレコードIDの順に取る方法です。前回取った最後のIDより大きいものを次に取ります。
1回目:order by $id asc limit 500
2回目以降:$id > 前回の最後のID order by $id asc limit 500
返ってきた件数が500未満になったら終わりです。ID順で困らない処理なら、これがいちばん素直です。
2つ目はカーソルです。日付順などで並べたまま全件を取りたいときに使います。
records/cursor.jsonにPOSTし、app、query、sizeを送ります。sizeは1回に取る件数で、500まで指定できます。queryにlimitとoffsetは書けません。- 返ってきたカーソルの
idを付けて、同じURLにGETします。 - レスポンスの
nextがtrueの間、2を繰り返します。 nextがfalseになったら全部取れています。カーソルは自動で消えます。
カーソルは最後に使ってから10分で切れます。有効なカーソルは1ドメインで10個までなので、途中でやめる処理では同じURLにDELETEでカーソルの id を送って消します。画面を開くたびに走るJavaScriptのように、同時にいくつも動く処理には向きません。
ファイルを添付する
ファイルの添付は2回に分けます。
file.jsonにPOSTでファイルを送り、返ってきたfileKeyを控えます。- レコードの登録か更新で、添付ファイルのフィールドの値にその
fileKeyを入れます。
curl -X POST 'https://example.cybozu.com/k/v1/file.json' \
-H 'X-Cybozu-API-Token: ここにAPIトークン' \
-F 'file=@見積書.pdf'
2の値は "見積書": { "value": [ { "fileKey": "控えたキー" } ] } の形です。レコードに付けないファイルは3日で消えます。既存のファイルを残して足すなら、既存の fileKey も一緒に送ります。ダウンロードは、レコードを取得したときの添付ファイルの値に入っている fileKey で file.json にGETします。アップロードで返る fileKey とは別物です。
アプリの設定を読む
app/form/fields.json にGETすると、フィールドコード、フィールド名、種類、選択肢がまとめて返ります。連携を組む前に1回取っておくと、フィールドコードの写し間違いがなくなります。設定を変えるAPIは、URLに preview/ が入る動作テスト環境に書き込み、preview/app/deploy.json を実行して初めて運用中のアプリに反映されます。
エラーの読み方
失敗すると、200番台以外のステータスコードと、id、code、message の3つを持つJSONが返ります。まず message を読みます。id はサポートに問い合わせるときに伝える番号です。
| 返ってくるもの | 原因 | 直し方 |
|---|---|---|
| CB_AU01「ログインしてください。」 | 認証のヘッダーが付いていない、ヘッダー名を間違えている | X-Cybozu-API-Token の綴りとコロンの位置を確かめる |
| GAIA_IA02「指定したAPIトークンは、アプリで生成されたトークンと異なります。」 | 別のアプリのトークン、写し間違い、発行後にアプリを更新していない | アプリIDとトークンの組を確かめ、アプリを更新する |
| 「権限がありません。」 | トークンに要る操作のチェックがない、ユーザーに権限がない | トークンのアクセス権を足し、アプリを更新する |
| CB_IJ01「不正なJSON文字列です。」 | 送ったJSONの形が崩れている | 引用符、カンマ、括弧の対応を確かめる |
| リビジョンの不一致のエラー | 取得したあとに誰かが更新した | 取得し直してから更新する |
| ステータスコード429 | 同時接続が100を超えた | 並列の数を減らし、時間をずらして再実行する |
GAIA_IA02のメッセージは、アプリを更新して反映する、というところまで書いてあります。トークンまわりで止まったら、メッセージを最後まで読みます。
エラーにならない警告もあります。like で絞った対象が100,000件に達すると検索が打ち切られ、レスポンスヘッダーの X-Cybozu-Warning に「Filter aborted because of too many search results」が付きます。
回数の制限と、超えないための書き方
1日のリクエスト数は、kintoneシステム管理の「アプリ管理」でアプリごとに見られます。超えると、サイボウズから確認の連絡が来たり、処理を止められたりすることがあります。超えないための書き方は3つです。
- 1件ずつではなく、取得は500件、登録・更新・削除は100件ずつまとめる
queryとfieldsで要るものだけ取る- 前回取得したあとの更新分だけを取る。条件は
更新日時 > "前回の取得時刻"のように書く
bulkRequest.json は回数を減らす手段ではありません。中で実行したAPIはそれぞれ1回と数えられます。使いどころは、1つでも失敗したら全部取り消したい処理です。見積と明細のように2つのアプリへ書く処理で、片方だけ残る事故を防げます。kintoneの画面で動かすJavaScriptでも、kintone.api() でREST APIを呼べば回数に数えられます。数えられないのは、kintone.app.getFormFields() のようにREST APIを呼ばないJavaScript APIです。

外部サービスとつなぐ
つなぎ方は2つの形に分かれます。kintoneで何か起きたら外へ知らせる形と、外から決まった時刻に取りに行く形です。
kintoneから外へ知らせる:Webhook
Webhookは、レコードの追加・編集・削除、コメントの書き込み、ステータスの更新が起きたときに、指定したURLへ通知を送る機能です。
- 受け取る側(ZapierのWebhookやn8nのWebhookノードなど)で受け口のURLを用意します。
- kintoneのアプリで「アプリを設定」をクリックします。
- 「設定」タブの「カスタマイズ/サービス連携」にある「Webhook」をクリックします。
- 「追加する」をクリックします。
- 説明を入れます(64文字まで)。
- 「Webhook URL」に受け口のURLを貼り付け、先頭の「https://」を消します。
- 「通知を送信する条件」で、通知を送る操作にチェックを入れます。
- 「このWebhookを有効にする」にチェックが入っていることを確かめます。
- 「保存」をクリックします。
- 「アプリの設定に戻る」をクリックします。
- 「アプリを更新」をクリックし、ダイアログでもう一度「アプリを更新」をクリックします。
通知には、type(ADD_RECORD など)、アプリ、レコードの値、レコードのURLが入ります。削除の通知は、レコードの値とURLの代わりに、レコード番号、削除した人、削除した日時が入ります。
送られない操作があります。ExcelやCSVの読み込み、複数レコードの一括削除、複数のレコードをまとめて操作するREST APIでは通知が出ません。ドメイン単位で1分間に60回を超えた分も送られず、データが1MBを超えると失敗します。まとめて読み込むアプリでWebhookに頼ると、取りこぼしが出ます。
送れたかどうかは、Webhookの一覧の「ログを確認」で直近10件まで見られます。緑のチェックが成功、赤の三角が失敗です。


外から取りに行く:定期実行
取りこぼしを許せない連携は、外のツールから決まった時刻にAPIで取りに行きます。スプレッドシートに毎朝写すなら、Google Apps Scriptの UrlFetchApp.fetch で records.json を呼び、ヘッダーに X-Cybozu-API-Token を付けて、時間主導型のトリガーで毎日動かします。トークンはコードに書かず、プロジェクトの設定の「スクリプト プロパティ」に入れます。muteHttpExceptions を true にすると、失敗したときもkintoneのエラーメッセージを読めます。トリガーは9時と指定しても9時から10時の間のどこかで動きます。
Slack・Teamsへの通知
kintoneのWebhookをSlackやTeamsの受け口に直接向けても、そのままでは投稿になりません。SlackのIncoming Webhookは本文の text が無いと受け付けず、TeamsのワークフローのWebhookはアダプティブカードなどのカードの形で送る必要があります。kintoneの通知は決まった形で送られるので、間にZapier、Power Automate、n8nなどを挟んで、文面を組み立ててから送ります。
標準の連携で足りることもあります。kintoneの「Slack連携」は、レコードの作業者になった人にSlackのダイレクトメッセージを送る機能です。Microsoft Power Automateには、レコードの追加・更新・削除などを起点に動くkintoneのコネクタがあります。どちらもライトコースでは使えず、Power Automateは有償プランの契約も要ります。
OAuthで外部サービスに使わせる
外部サービスに、使う人ごとの権限で操作させるならOAuthです。cybozu.com共通管理者が「OAuth」の「OAuthクライアントの追加」でクライアント名とリダイレクトエンドポイントを登録し、発行されたクライアントIDとシークレットを連携先に渡して、「利用者の設定」で使う人にチェックを入れます。範囲はスコープで決まり、読むだけなら k:app_record:read です。アクセストークンは1時間で切れ、リフレッシュトークンで取り直します。

安全に使うための注意
APIトークンは、そのアプリのデータを持ち出せる鍵です。扱いは次のように決めておきます。
- 連携ごとに別のトークンを発行し、メモに用途と担当者を書く
- 付ける権限は要る操作だけにする。読むだけの連携に編集や削除を付けない
- トークンを、kintoneに読み込ませるJavaScriptファイルやプラグインの設定に書かない。利用者が見られる場所に置くことになる
- 外のサーバーやスクリプトでは、設定ファイルやスクリプト プロパティなど、コードと分けた場所に置く
- 連携をやめたら、トークンを削除してアプリを更新する
トークンのアクセス権はアプリやレコードのアクセス権より優先されるので、一部の人にしか見せていないフィールドも連携先から読めます。その前提で発行するかを決めます。組織間のアクセスを禁止する設定にしていると、トークンの発行と確認はkintoneシステム管理者しかできません。

できないことと、その代わり
| やりたいこと | 標準でできるか | 代わりの手 |
|---|---|---|
| ライトコースでAPIを使う | できない | スタンダードコースに変える |
| 計算、カテゴリー、ルックアップのコピー先をAPIで直接書く | できない | 元になる値やルックアップのキーを書く |
| ステータスや作業者を通常の更新で変える | できない | ステータスの更新、作業者の更新のAPIを使う |
| 1回で501件以上、offsetで10,001件目以降を取る | できない | ID順に分けて取るか、カーソルを使う |
| 読み込みや一括操作でもWebhookを出す | できない | 外から定期的に取りに行く |
| WebhookでSlackやTeamsに直接投稿する | 形が合わない | Zapier、Power Automate、n8nを挟む |
| APIトークンでシステム管理の操作をする | できない | パスワード認証かOAuthを使う |
| トークンで操作した人を記録する | Administratorの操作になる | 担当者のフィールドを持たせて連携側で入れる |
| 削除したレコードを戻す | できない | 削除の権限を付けたトークンを絞り、定期的に書き出しておく |
よく詰まるところ
| 症状 | 原因 | 直し方 |
|---|---|---|
| トークンを作ったのにGAIA_IA02が返る | アプリを更新していない | 「アプリを更新」を押す |
| 登録は成功したのに一部の欄が空 | フィールドコードの写し間違い。存在しないコードは無視される | フィールド一覧のAPIでコードを取り、照らし合わせる |
| 日時が9時間ずれる | 時差を付けずに送った、返ってきたUTCをそのまま表示した | 送るときは +09:00 を付け、受けたら9時間足す |
| 合計が文字のつながりになる | 数値が文字列で返っている | 受け取った側で数値に直してから計算する |
| テーブルの行が消えた | 一部の行だけを送って更新した | 残す行を全部、行の id 付きで送る |
| 1万件を超えたところで止まる | offsetの上限 | ID順の取得かカーソルに書き換える |
| カーソルが作れなくなった | 途中でやめたカーソルが残り、10個に達した | 途中でやめるときはDELETEで消す。10分待つと切れる |
| 夕方に連携が止まる | 1日のリクエスト数を使い切った | 500件・100件ずつまとめて扱う、差分だけ取る |
| CSVで入れたレコードの通知が外に来ない | 読み込みではWebhookが送られない | 定期的に取りに行く形に変える |
| ルックアップの値が入らない | コピー元のアプリのトークンが無い | コピー元のトークンもカンマ区切りで並べる |
| 2要素認証のユーザーで認証が通らない | 2要素認証ではパスワード認証が使えない | APIトークンか、連携専用のユーザーを使う |
| 添付したファイルが3日後に消えた | アップロードだけしてレコードに付けていない | 続けてレコードの登録か更新で fileKey を入れる |
| APIでフィールドを足したのに画面に出ない | 動作テスト環境に書いただけ | preview/app/deploy.json で運用環境に反映する |
次にやること
kintoneの画面の中でAPIを呼ぶなら「kintoneのJavaScriptカスタマイズ入門。最初の1本を動かすまで」が続きです。コードを書かずに連携を足したいなら「kintoneのプラグインとは。入れ方・選び方・注意点」を読みます。スプレッドシートへ写す仕組みは「kintoneとGoogleスプレッドシートの連携」、チャットへの通知は「kintoneとSlack/Teamsの通知連携」に、具体的な組み方をまとめています。