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 “\” |
Date formats
Date and time related fields follow the following formats.
FIELD TYPE | FORMAT | DESCRIPTION |
---|---|---|
Date | YYYY-MM-DD | This is not converted to UTC. The below date formats can be used:
|
Time | HH:MM:SS | This is not converted to UTC. |
Date and time | YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS±HH:MM |
Symbols
|
Authentication
Refer to Authentication .
Request headers
These request headers are used for the REST API.
HEADER | VALUE |
---|---|
Host | {subdomain}.kintone.com:443 |
Content-Type | application/json |
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.
* If a GET request is sent using kintone.api()
and the length exceeds 4KB, the X-HTTP-Method-Override header will automatically be added and the request will be sent as a POST request.The below request will run the Get Records API . Request Header POST /k/v1/records.jsonRequest Body { |
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. |
SAML Environments
Security Assertion Markup Language (SAML) is an authentication option that allows for Kintone login via a company’s Identity Provider (IdP). The SAML redirect can be bypassed by placing saml=off in the parameter of the login URL. This bypassing method can be restricted to only the
Users & System Administrators
, if the “Require SAML authentication” checkbox is checked in the SAML Authentication settings. Checking this checkbox also restricts access of API calls from certain types of authentications:
- Subdomains with the “Require SAML authentication” checkbox unchecked:
APIs may be authenticated via Password Authentication
APIs may be authenticated via API Token Authentication
APIs may be authenticated via OAuth - Subdomains with the “Require SAML authentication” checkbox checked:
APIs may be authenticated via Password Authentication but limited to only User and System Administrators
APIs may be authenticated via API Token Authentication
APIs may be authenticated via OAuth
For step-by-step instructions on enabling this SAML Authentication feature, refer to the
Requiring Users to Login Through SAML Authentication
Kintone Help Center article.
Responses
Error responses
HTTP status code 200 denotes that the request was successfully received.
Treat any other status code as errors. Errors will respond with JSON data including the following information.
KEY | VALUE |
---|---|
message | The error message. The language of the message will differ depending on the Kintone user’s language settings. |
id | The ID of the error. |
code | The code of the error, to specify the type of error it is. |
Sample Error Response
|
|
Concurrency limits
All Kintone REST APIs include the following details in the response header.
KEY | VALUE |
---|---|
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 making a Kintone REST API request with kintone.api()
, the information returned in the callback is only the response body. To use information outside of the response body, use a different request from kintone.api().
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. Refer to
Monitoring Audit Logs
from the Kintone Help Center for more details.
- The following APIs are not counted as part of the API call limits:
- If a domain has IP address restriction, only API requests from an approved IP address will be successful.
Limitations
- The number of records that can be retrieved at once is 500.
- The number of records that can be created/updated/deleted at once is 100.
- The number of comments that can be retrieved from a record at once is 10.
- The number of rows that can be added into a
table
is 5000.
- The concurrent API request limit is 100.
- 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.
- If the request of the Get Record(s) API, Add Record(s) API and the Update Record(s) API includes field codes that do not exist, those field codes will be ignored.
- The following fields can be retrieved, but cannot be created or updated:
- Files that are uploaded onto Kintone using the Upload File API will further need the Add Record API or Update Record API for the file to be added onto a record field. If this is not done, the file will stay in the server until it is deleted 3 days after. While the file is on the server, this will also take up the shared disk space.