kintone REST APIは、kintoneのアプリやレコード、スペースを操作できるAPIです。
このページでは、kintone REST APIの共通仕様を説明します。
各APIの仕様の詳細は、それぞれのAPIのページを確認してください。

APIによって異なります。

RESOURCEは、APIによって異なります。
詳細は各APIのページを確認してください。

通常（ゲストスペース以外）

https://sample.cybozu.com/k/v1/RESOURCE

ゲストスペース

https://sample.cybozu.com/k/guest/SPACE_ID/v1/RESOURCE

送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST APIリクエストを送信するAPI（kintone.api()）を使って、kintone REST APIを実行する場合、リクエストヘッダーの指定は不要です。
kintone REST APIリクエストを送信するAPI

Host

Garoon REST APIを実行するドメインとポート番号（443）を、「ドメイン:ポート番号」の形式で指定します。
Hostは必須です。

Content-Type

指定する値はリクエストボディの形式によって異なります。

• JSON文字列の場合：application/json
• マルチパートの場合：multipart/form-data

リクエストボディを送信する場合のみ指定します。

X-Cybozu-Authorization

「ログイン名:パスワード」をBase64エンコードした値を指定します。
パスワードを使って認証する場合のみ指定します。
パスワード認証の詳細は、次のページを参照してください。
パスワード認証

X-Cybozu-API-Token

kintoneのAPIトークンを指定します。
APIトークンを使って認証する場合のみ指定します。
APIトークン認証の詳細は、次のページを参照してください。
APIトークン認証

X-Requested-With

「XMLHttpRequest」または空文字列以外の文字列を指定します。
セッションで認証する場合のみ指定します。
セッション認証の詳細は、次のページを参照してください。
セッション認証

Authorization

次の値を半角スペースで結合した値を指定します。

• Basic
• 「Basic認証のユーザー名:Basic認証のパスワード」をBase64エンコードした値

Basic認証を設定している場合のみ指定します。
Basic認証を設定している環境でのリクエスト方法は、次のページを参照してください。
Basic認証を設定している環境

X-HTTP-Method-Override

実行するAPIのHTTPメソッド（GET／POST／PUT／DELETEのいずれか）を大文字で指定します。
このヘッダーにHTTPメソッドを指定してPOSTリクエストを送信すると、指定したHTTPメソッドに対応するAPIが実行されます。

リクエストURLが8KBを超える場合に指定すると、Request URL Too Largeエラーを回避できます。

たとえば、次のリクエスト例はレコードを複数取得するAPIを実行できます。

1
2
3
4
5

curl -X POST https://sample.cybozu.com/k/v1/records.json \
  -H 'X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=' \
  -H 'Content-Type: application/json'  \
  -H 'X-HTTP-Method-Override: GET' \
  -d '{ "app": 1, "query": "更新日時 > \"2024-02-03T09:00:00Z\"" }'

このヘッダーは、すべてのkintone REST APIで利用できます。
ただし、外部のAPIを実行するAPIでkintone REST APIを実行したときの動作はサポートしていません。
外部のAPIを実行する

Accept-Language

cybozu.comで利用できる表示言語の言語コードを指定します。
表示言語が「Webブラウザーの設定に従う」の場合、このヘッダーで指定した言語がレスポンスボディの言語に反映されます。

リクエスト結果の表示言語を指定したい場合のみ指定します。

JSON形式で指定します。文字コードはUTF-8です。
ただし、ファイルをアップロードするAPIはマルチパート形式で指定します。
ファイルをアップロードするAPI

JSON文字列でエスケープが必要な文字は、\でエスケープしてください。

GETメソッドのAPIでは、URLのクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターのappが「1」の場合、クエリパラメーターは次のように指定します。

1

/k/v1/records.json?app=1

エスケープ

URLの仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「更新日時 > "2024-10-01T09:00:00+0900"」をパーセントエンコーディングした例です。

1

/k/v1/records.json?app=1&query=%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3E%20%222024-10-01T09%3A00%3A00%2B0900%22%20

配列型のパラメーターを指定する場合

配列を要素に分解してパーセントエンコーディングします。

リクエストパラメーターのfieldsに、「レコード番号」と「ドロップダウン」を指定する例を示します。

1. fields=[レコード番号,ドロップボックス]という配列を要素に分解します。

   1	/k/v1/records.json?app=1&fields[0]=レコード番号&fields[1]=ドロップダウン

2. クエリパラメーターのキーや値をパーセントエンコーディングします。

   1	/k/v1/records.json?app=1&fields%5B1%5D=%e4%bd%9c%e6%88%90%e6%97%a5%e6%99%82&fields%5B2%5D=%e3%83%89%e3%83%ad%e3%83%83%e3%83%97%e3%83%80%e3%82%a6%e3%83%b3

リクエストに成功した場合、200番台のステータスコードが返ります。
リクエストに失敗した場合、200番台以外のステータスコードとエラーレスポンスが返ります。
エラーレスポンス

X-ConcurrencyLimit-Limit

同時接続数の上限値です。
必ず100が返ります。

X-ConcurrencyLimit-Running

現在の同時接続数です。

kintone REST APIリクエストを送信するAPIで実行した場合

kintone REST APIリクエストを送信するAPIを使って、kintone REST APIを実行した場合、コールバック関数に渡される情報は、レスポンスボディだけです。
レスポンスボディ以外の情報を利用する場合には、kintone REST APIリクエストを送信するAPI（kintone.api()）以外の方法で、kintone REST APIを実行してください。
kintone REST APIリクエストを送信するAPI

JSON形式で返されます。文字コードはUTF-8です。
ただし、ファイルをダウンロードするAPIでは、バイナリデータが返されます。
ファイルをダウンロードするAPI

次のプロパティをもつオブジェクトがJSON形式で返されます。

パラメーター名	型	説明
id	文字列	エラーID サポートへの問い合わせの際に利用します。
code	文字列	エラーの種類を表すコード
message	文字列	エラーメッセージ 出力されるメッセージの言語は、APIを実行したユーザーの表示言語の設定によって異なります。 表示言語の設定

エラーの例

1
2
3
4
5

{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "不正なJSON文字列です。"
}

日時を扱うフィールドでは、次の形式の文字列を指定してください。

フォーマット

YYYY-MM-DD

補足

次の形式も許容されます。

• YYYY（例：2024）
• YYYY-MM（例：2024-07）
• YYYY-M（例：2024-7）
• YYYY-M-D（例：2024-7-5）

月日を省略すると01で補完され、桁数が足りない場合は0埋めされます。

• 2024 → 2024-01-01
• 2024-07 → 2024-07-01
• 2024-7 → 2024-07-01
• 2024-7-5 → 2024-07-05

フォーマット

HH:MM

補足

UTCには変換されません。

フォーマット

YYYY-MM-DDTHH:MM:SSZ

補足

たとえば、日本時間（JST）の2024年3月22日14時00分は、「2024-03-22T05:00:00Z」と表します。
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「Z」はUTCを表します。

「T」以降を省略した場合、UTC 0時の指定と同等です。
例：2024-03-22を指定した場合、2024-03-22T00:00:00Zと同等になります。

一覧の設定を取得するAPIでは、日時はUTCで出力されます。
一覧の設定を取得するAPI

フォーマット

YYYY-MM-DDTHH:MM:SS±HH:MMまたはYYYY-MM-DDTHH:MM:SSZ

補足

たとえば、日本時間（JST）の2024年3月22日14時17分は、次のように表します。
「2024-03-22T14:17:00+09:00」「2024-03-22T05:17:00Z」

「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。

「±HH:MM」には、UTCとの時刻の差を指定します。

「T」以降を省略した場合、UTC 0時の指定と同等です。
例：2024-03-22を指定した場合、2024-03-22T00:00:00Zと同等になります。

秒情報を指定して登録または更新を行と、秒情報は無視されます。
たとえば、「2024-02-06T12:59:59Z」と指定すると、「2024-02-06T12:59:00Z」として登録または更新されます。

• リクエストデータ、およびレスポンスデータのJSONフォーマットには、今後フィールドやキーなどが追加される場合があります。
• REST APIを実行すると監査ログに記録されます。
  kintoneの監査ログの確認方法／ログ一覧

同時にリクエストできるAPIは、1ドメインにつき100までです。

1つのアプリにつき実行できるAPIのリクエスト数の上限は、次のとおりです。

• スタンダードコース：10,000件
• ワイドコース：100,000件

リクエスト数にカウントされないAPIは、次のページを確認してください。
1日に実行できるAPIリクエスト数

• 複数のレコードを取得するAPIのoffsetで指定できるレコードの上限数は、10,000件までです。
  複数のレコードを取得するAPI
• 一度に登録／更新／削除できるレコードは、100件までです。
• 1つのテーブルに大量の行を追加しないでください。
  アプリの構成によっては負荷がかかり、レコードの表示やREST APIを使った操作などのレコードの処理に影響します。
  kintoneの性能を考慮したレコードの操作方法は、次のTipsを参照してください。
  kintoneの性能改善
• 存在しないフィールドコードを指定して、レコードを取得／登録／更新した場合でも、存在しないフィールドコードは無視されて処理されます。
• 次のフィールドは、値の取得のみです。登録や更新はできません。
  • ルックアップフィールドによって値が入力されるフィールド
  • カテゴリー
  • 計算
  • ステータス
    更新する場合は、レコードのステータスを更新するAPIを使います。
    レコードのステータスを更新するAPI
  • 作業者
    更新する場合は、レコードの作業者を更新するAPIを使います。
    レコードの作業者を更新するAPI
• レコードの登録や更新をするAPIでルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」は、「レコード番号」フィールド、または「値の重複を禁止する」を設定したフィールドを指定してください。
• ルックアップフィールドの「コピー元のフィールド」に、自動計算を設定している「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

アップロードしたファイルは、一時保管領域に保存されます。
レコードの登録や更新をするAPIでレコードに添付しない限り、3日間で削除されます。
一時保管領域に保存したファイルは、ディスク使用量に含まれます。

一度に取得できるレコードのコメントは10件までです。

• kintoneに関するその他の制限事項
  制限値一覽
• その他、サービスに関する制限事項
  • サイボウズのクラウドサービス制限事項