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請求的APIkintone.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 token。
僅指定要使用 API 令牌進行身份驗證的情況。
有關更多資訊，請參閱以下頁面。
API 權杖身分驗證

X-Requested-With

指定「XMLHttpRequest」或非空字串。
僅當要通過會話進行身份驗證時才指定。
有關詳細的會話驗證，請參閱以下頁面。
會話認證

Authorization

指定以下值與單位元組空格組合。

• Basic
• 「基本認證使用者名:基本認證密碼」的Base64編碼值

僅在配置基本身份驗證時指定。
在配置了基本認證的環境中，如何發出請求，請參考以下頁面。
具有Basic身分驗證的環境

X-HTTP-Method-Override

以大寫形式指定要執行的 API 的 HTTP 方法（GET/POST/PUT/DELETE）。
如果使用此頭中指定的 HTTP 方法發送 POST 請求，則將執行指定 HTTP 方法對應的 API。

如果指定請求 URL 大於 8 KB，則可以避免「請求 URL 過大」錯誤。

例如，以下範例請求可以運行獲取多條記錄的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。
但是，當kintone REST API與執行外部API的API一起執行時，它不支援這種行為。
執行外部 API

Accept-Language

指定 cybozu.com 中可用的顯示語言的語言代碼。
如果顯示語言為「與網路瀏覽器設定相同」，則此標頭中指定的語言將反映在回應正文的語言中。

僅當要指定請求結果的顯示語言時才指定。

以 JSON 格式指定。字元編碼為UTF-8。
但是，用於上傳檔案的 API 是以分段格式指定的。
上傳檔案的 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%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～299範圍內的狀態代碼。
如果請求失敗，則返回200～299範圍外的狀態代碼和錯誤回應。
錯誤回應

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（例如：2015-7-5）
• YYYY-MM（例如：2015-7-5）
• YYYY-M（例如：2015-7-5）
• YYYY-M-D（例如：2015-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） 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 0點鐘位置的規格。
示例：如果指定了 2024-03-22，則相當於 2024-03-22T00：00：00Z。

在用於獲取清單中設置的 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 0點鐘位置的規格。
示例：如果指定了 2024-03-22，則相當於 2024-03-22T00：00：00Z。

如果在寄存器或更新行中指定秒資訊，則將忽略秒資訊。
例如「2019-02-06T12:59:59Z」註冊或更新為「2019-02-06T12:59:00Z」。

• 請求和回應數據的 JSON 格式可能包括其他欄位、鍵等。
• 運行 REST API 時，它會記錄在審核日誌中。
  kintone/日誌清單的審計日誌查詢方法

每個域一次最多可以請求 100 個 API。

每個應用程式可以發出的最大 API 請求數如下：

• 標準版：10,000
• WIDE版： 100,000

對於不計入請求數的 API，請查看以下頁面：
每個應用程式一天中可執行的API請求數

• 選取多條記錄API的offset中可以指定的最大記錄數為 10,000。
  獲取多條記錄
• 您一次最多可以建立/更新/刪除 100 條記錄。
• 不要向單個表添加大量行。
  根據應用的配置方式，它可能會很昂貴，並且會影響記錄的處理，例如查看記錄或使用 REST API 與記錄交互。
  關於如何考慮kintone性能的記錄，請參見以下提示。
  提高kintone的性能
• 即使您指定了不存在的域代碼並獲取/創建/更新記錄，也將忽略並處理不存在的域代碼。
• 以下欄位僅用於值獲取。它不能註冊或更新。
  • 由Lookup欄位輸入其值的欄位
  • 類別
  • 計算
  • 狀態
    如果要更新，請使用更新單個記錄的狀態API。
    更新多條記錄的狀態
  • 執行者
    如果要更新，請使用更新記錄上的執行者API。
    更新記錄上的執行者
• 如果要變更 API 中用於註冊或更新記錄的Lookup欄位的值，請將「記錄編號」欄位或帶有「值為唯一」的欄位指定為Lookup欄位的「要複製的欄位」。
• 如果Lookup欄位的「要複製的欄位」選擇設置為自動計算的「單行文字方塊」欄位，則無法變更Lookup欄位的值。

上傳的檔存儲在臨時存儲區。
除非您使用 API 將其附加到記錄以註冊或更新記錄，否則它將在 3 天內被刪除。
保存到臨時存儲的檔包含在磁碟使用量中。

您一次只能獲取一條記錄的 10 條回覆。

• kintone的其他限制
  限值一覽
• 服務的其他限制
  • Cybozu Cloud 服務限制