kintone REST API の共通仕様

目次

kintone REST API は、kintone のアプリやレコード、スペースを操作できる API です。

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

\ を使用します。

日時のフォーマット

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

日付

フォーマット
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」として登録または更新されます。

リクエスト

URL

ゲストスペース以外

https://sample.cybozu.com/k/v1/リソース

ゲストスペース内のアプリ

https://sample.cybozu.com/k/guest/スペースのID/v1/リソース

リクエストヘッダー

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

ヘッダー名 必須 内容
Host 必須 sample.cybozu.com:443
Content-Type 省略可 application/json
リクエストボディに JSON 文字列を指定する場合は必須です。
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 リクエストとして送信されます。

レスポンス

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 フォーマットには、今後フィールドやキーなどが追加される場合があります。
  • REST API を実行すると監査ログに記録されます。詳細は kintoneの監査ログの確認方法/ログ一覧 (External link) を参照してください。
  • 1 日に実行できる API は、1 つのアプリにつき 10,000 件までです。ただし、次の API はリクエスト数にカウントされません。
    • ファイルのダウンロード
    • ファイルのアップロード
    • スペース情報の取得
    • スペースの作成
    • スペースの本文の更新
    • スペースのスレッドの更新
    • スペースのスレッドへの投稿
    • スペースのメンバーの取得
    • スペースのメンバーの更新
    • ゲストスペースのゲストメンバーの更新
    • ゲストユーザーの一括追加
    • ゲストユーザーの一括削除
    • スペースの削除
    • API 一覧の取得
    • API スキーマ情報の取得

制限事項

同時接続数

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

レコードを操作する API

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

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

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

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

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

その他の制限事項