Kintone REST API Overview
The Kintone REST API
The Kintone REST API is capable of general create/retrieve/update/delete operations of App records, retrieving App descriptions, and manipulation of Spaces.
PROTOCOL | FORMAT | CHARACTER ENCODING | ESCAPE SEQUENCE |
---|---|---|---|
HTTPS | JSON | UTF-8 | Use \ |
Authentication
Refer to the following article:
Authentication
Requests
Request URI
PURPOSE | URI | DETAILS |
---|---|---|
General | https://{subdomain}.kintone.com/k/v1/{APIpath}.json | This is the general request URI you should be using. If you are dealing with apps that are in guest spaces, use the below request URI. |
Apps in guest spaces | https://{subdomain}.kintone.com/k/guest/{spaceID}/v1/{APIpath}.json | If the app was made inside a guest space, this is the request URI you will need to use. Note that guest users cannot initiate REST APIs. |
Request Headers
These request headers are used for the REST API.
It is not necessary to specify request headers when using a Kintone REST API request, kintone.api()
. For more information, refer to the following article:
Kintone REST API request
Host
The value is {subdomain}.kintone.com:443
.
Host is required.
Content-Type
The specified value depends on the format of the request body.
- For JSON:
application/json
- For multipart data:
multipart/form-data
Only required when sending a request body.
X-Cybozu-Authorization
login_name:password
encoded in base64.
Only required when using password authentication. For more information, refer to the following article:
Password Authentication
X-Cybozu-API-Token
The Kintone App's API Token.
Only required when using API Token Authentication. For more information, refer to the following article:
API Token Authentication
X-Requested-With
XMLHttpRequest
or strings that are not empty.
Only required for session authentication. For more information, refer to the following article:
Session Authentication
X-HTTP-Method-Override
The HTTP method. Specify one of the following: GET
/ POST
/ PUT
/ DELETE
.
By specifying an HTTP method on the X-HTTP-Method-Override
and sending a POST
request, an API that corresponds to the specified HTTP method will run.
- The X-HTTP-Method-Override header will only be valid during a
POST
request. - The HTTP method specified for X-HTTP-Method-Override is case-sensitive.
- The
Request URI Too Large
error can be avoided by specifying this method when the request URI exceeds 8KB. - This header method is available on all Kintone REST API routes, but behavior can not be guaranteed when using with external APIs. For more information, refer to the following article:
External API Requests
X-HTTP-Method-Override example
The below request will run the following API:
Get Records
|
|
Accept-Language
The Language Code, e.g.en
, ja
, zh
, es
.
If the display language is set to Using web browser settings, the response will be returned in the specified language.
Specify this header only when designating the display language of the request result.
Request Body
The request body is formatted in JSON. Character encoding should be in UTF-8.
However when using the File Upload API, the request body should be formatted as multipart/form-data
. For more information, refer to the following article:
File Upload
A backslash \
can be used to escape characters within the JSON as necessary.
Query Parameters
For API routes using the GET
method, request parameters can be passed via the URL as query parameters. For example, to specify an App Id
of 1, query parameters can be set like the following:
|
|
Encoding
According to the URL Standard, keys and values of query parameters are encoded using URL Encoding. The example below shows a URL encoded string for Updated_datetime > "2024-10-01T09:00:00+0900":
|
|
Array parameters
Decompose the array, and URL encode each element.
In the following example, the Get Records API is used. The fields
parameter includes a Record Id
field and a Dropdown
field. For more information, refer to the following article:
Get Records
-
fields=[Record_Id,Dropdown]
is decomposed into separate elements:1
/k/v1/records.json?app=1&fields[0]=Record_Id&fields[1]=Dropdown
-
The keys and values of each parameter are URL encoded:
1
/k/v1/records.json?app=1&fields%5B0%5D%3DRecord_Id%26fields%5B1%5D%3DDropdown
Responses
HTTP Status Codes
HTTP status code 200 denotes that the request was successfully received.
Treat any other status codes as errors. For more information on error response, refer to the following section:
Error Response
Response Headers
All Kintone REST APIs include the following details in the response header.
X-ConcurrencyLimit-Limit
The concurrent API Request Limit.
The default value is 100.
X-ConcurrencyLimit-Running
The number of running concurrent API requests.
About the Response of a Request Made With kintone.api()
When using kintone.api()
to make requests for Kintone REST APIs, only the response body is passed to the callback function. To use other data that are not included in the response body, refrain from using kintone.api()
and instead use another method.
Kintone REST API Request
Response Body
Returned in JSON format. The character encoding is UTF-8.
However, the API for downloading files returns binary data:
Download File
Error Response
An object with the following properties is returned in JSON format.
KEY | VALUE |
---|---|
id | The ID of the error. |
code | The code of the error, to specify the type of error it is. |
message | The error message. The language of the message will differ depending on the Kintone user's language settings. |
Sample error response
|
|
Date Formats
Date and time related fields follow the following formats.
Date
Format
YYYY-MM-DD
Description
This is not converted to UTC. The below date formats can be used:
YYYY
(e.g. 2024)YYYY-MM
(e.g. 2024-08)YYYY-M
(e.g. 2024-8)YYYY-M-D
(e.g. 2024-8-1)
If the date and/or month is ignored, it will be supplemented with 01:
- 2024 → 2024-01-01
- 2024-08 → 2024-08-01
- 2024-8 → 2024-08-01
- 2024-8-1 → 2024-08-01
Time
Format
HH:MM
Description
This is not converted to UTC.
Date and time (For Responses)
Format
YYYY-MM-DDTHH:MM:SSZ
Description
For example, 22nd August 2024 07:00 PST will be responded as 2024-08-22T15:00:00Z.
The symbol Z indicates that the date time is expressed in UTC.
The symbol T is a fixed value to separate the date from the time. When omit after T, it is considered as 00:00 UTC. For example, 2024-08-01 will be responded as 2024-08-01T00:00:00Z.
The date and time in the Get Views API output are in UTC. For more information, refer to the following article:
Get Views
Date and time (For Requests)
Format
YYYY-MM-DDTHH:MM:SS±HH:MM
or YYYY-MM-DDTHH:MM:SSZ
Description
For example, 22nd August 2024 07:23 PST can be requested as 2024-08-22T15:23:00Z or 2024-08-22T07:23:00-08:00.
The symbol Z indicates that the date time is expressed in UTC.
The symbol T is a fixed value to separate the date from the time. When omit after T, it is considered as 00:00 UTC. For example, 2024-08-01 will be responded as 2024-08-01T00:00:00Z.
±HH:MM specifies the time difference from UTC.
Values stated for SS will be ignored, and will be treated as 00. For example, 2024-08-01T12:59:59Z will be responded as 2024-08-01T12:59:00Z.
Notes
- After Kintone updates, spec changes such as the addition of new fields and keys may be applied to the JSON formats of the request and response data.
- To view information of App, Record, Comment, and Space operations, view the audit logs. For more details, refer to the following article:
Checking Kintone Audit Logs - The number of API requests available per day is 10,000 per App. For APIs that are not counted as part of the API call limits, refer to the following link:
The number of API requests available per day - If a domain has IP address restriction, only API requests from an approved IP address will be successful.
Limitations
Number of Concurrent API Request
- 100 concurrent requests per domain
The Number of API Requests Available Per Day
- 10,000 requests per app
For APIs that are not counted in the number of requests, refer to the following article on the Kintone Help site:
The number of API requests available per day
API for Manipulating App Records
- The maximum number of records that can be specified in the
offset
parameter of the Get Records API is 10,000. For more information, refer to the following article:
Get Records - The maximum number of records that can be added, updated, or deleted at once: 100
- Do not add large numbers of rows to a single table. Depending on the App's configuration, the load can affect record processing, such as displaying records in the View screen or manipulating records using the REST API.
- When operating on Lookup values with the Add Record(s) API and the Update Record(s) API, the Key Field of the Datasource App must be either a Record Number field or a field with the Prohibit duplicate values option turned on.
- If the Key Field of the Datasource App of a Lookup field is a Text field with the "Calculate automatically" option turned on, the Lookup field cannot be operated on with API.
- For more information, refer to the following article on the Kintone Help site:
API for manipulating app records
Retention Period for an Uploaded File
- Uploaded files are stored in the temporary storage area, and deleted three days after the upload unless the file is attached to a record by Add Record API or Update Record API.
- Files stored in the temporary storage area are included in the disk usage.
API for App Record Comments
- The maximum number of comments that can be retrieved at once: 10
Others
For more information on the limitations and usage of the Kintone REST API, refer to the REST API section of the following article on the Kintone Help site:
List of Limit Values
Features Removed
Request Header: Authorization
Basic
followed by a Base64 encoded login_name:password
. It is only required when using the deprecated Basic Authentication, which is no longer available as of June 2020. For more information, refer to the following article:
Basic Authentication