kintone API ドキュメント

kintone REST API の共通仕様

目次

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

リクエスト

HTTP メソッド

API によって異なります。

URL

通常（ゲストスペース以外）
https://sample.cybozu.com/k/v1/リソース
ゲストスペース
https://sample.cybozu.com/k/guest/スペースのID/v1/リソース

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

リクエストヘッダー

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

ヘッダー名 必須 内容
Host 必須 sample.cybozu.com:443
Content-Type 条件必須 リクエストボディを送信する場合のみ指定します。
指定する値はリクエストボディの形式によって異なります。
  • JSON 文字列の場合：application/json
  • マルチパートの場合：multipart/form-data
X-Cybozu-Authorization 条件必須 「ログイン名:パスワード」を Base64 エンコードした値
パスワードを使って認証する場合は、必須です。
詳細は、 パスワード認証 を参照してください。
X-Cybozu-API-Token 条件必須 kintone の API トークン
API トークンを使って認証する場合は必須です。
詳細は、 APIトークン認証 を参照してください。
Authorization 条件必須 「Basic 」と「"Basic認証のユーザー名:Basic認証のパスワード" を Base64 エンコードした値」を結合した値
Basic 認証 を設定している場合、必須です。
詳細は、 Basic 認証を設定している環境 を参照してください。
X-HTTP-Method-Override 省略可 HTTP メソッド（GET／POST／PUT／DELETE）
このヘッダーは、リクエスト URL が 8 KB を超えると発生する Request URL Too Large エラーを回避する目的で使用します。

「X-HTTP-Method-Override」に HTTP メソッドを指定して POST リクエストを送信すると、指定した HTTP メソッドに対応する API が実行されます。
以下は、ヘッダーを付けて レコードを複数取得する API を実行するときの例です。
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": "更新日時 > \"2012-02-03T09:00:00Z\"" }'
このヘッダーは、すべての kintone REST API で利用できますが、 外部の API を実行する API で実行した場合の動作はサポートしていません。
「X-HTTP-Method-Override」に指定する HTTP メソッドは、大文字を指定してください。
kintone REST API リクエストを送信する API で URL の長さが 4 KB を超える GET リクエストを送信した場合、「X-HTTP-Method-Override」ヘッダーが自動的に付与され、POST リクエストとして送信されます。

リクエストボディ

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

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

クエリパラメーター

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

1

/k/v1/records.json?app=1
エスケープ

URL の仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「更新日時 > "2021-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%222012-02-03T09%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

レスポンス

HTTP ステータスコード

リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと、次のプロパティをもつオブジェクトが返ります。

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

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

レスポンスヘッダー

パラメーター名 型 説明
X-ConcurrencyLimit-Limit 数値 同時接続数の上限値
必ず 100 が返ります。
X-ConcurrencyLimit-Running 数値 現在の同時接続数
kintone REST API リクエストを送信する API で実行した場合

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

レスポンスボディ

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

日時のフォーマット

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

日付

フォーマット
YYYY-MM-DD
補足
次の形式も許容されます。
  • YYYY（例：2015）
  • YYYY-MM（例：2015-07）
  • YYYY-M（例：2015-7）
  • YYYY-M-D（例：2015-7-5）
月日を省略すると 01 で補完され、桁数が足りない場合は 0 埋めされます。
  • 2015 → 2015-01-01
  • 2015-07 → 2015-07-01
  • 2015-7 → 2015-07-01
  • 2015-7-5 → 2015-07-05

時刻

フォーマット
HH:MM
補足
UTC には変換されません。

日時（取得するとき）

フォーマット
YYYY-MM-DDTHH:MM:SSZ
補足
たとえば、日本時間（JST）の 2012 年 3 月 22 日 14 時 00 分は、「2012-03-22T05:00:00Z」と表します。
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「Z」は UTC を表します。
「T」以降を省略すると、UTC として扱われます。
一覧の設定を取得する API では、日時は UTC で出力されます。

日時（登録または更新するとき）

フォーマット
YYYY-MM-DDTHH:MM:SS±HH:MM または YYYY-MM-DDTHH:MM:SSZ
補足
たとえば、日本時間（JST）の 2012 年 3 月 22 日 14 時 17 分は、次のように表します。
「2012-03-22T14:17:00+09:00」「2012-03-22T05:17:00Z」
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「±HH:MM」には、UTC との時刻の差を指定します。
「T」以降を省略すると、UTC として扱われます。
秒情報を指定して登録または更新を行と、秒情報は無視されます。
たとえば、「2019-02-06T12:59:59Z」と指定すると、「2019-02-06T12:59:00Z」として登録または更新されます。

注意事項

  • リクエストデータ、およびレスポンスデータの JSON フォーマットには、今後フィールドやキーなどが追加される場合があります。
  • REST API を実行すると監査ログに記録されます。詳細は kintoneの監査ログの確認方法／ログ一覧 (External link) を参照してください。
  • 1 日に実行できる API は、1 つのアプリにつき 10,000 件までです。
    リクエスト数にカウントされない API は、 1日に実行できるAPIリクエスト数 (External link) を確認してください。

制限事項

同時接続数

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

レコードを操作する API

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

ファイルをアップロードする API

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

レコードにコメントする API

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

その他の制限事項