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.


Date formats

Date and time related fields follow the following formats.

Date YYYY-MM-DD This is not converted to UTC.
The below date formats can be used:
* 2015
* 2015-07
* 2015-7
* 2015-7-5
If the date and/or month is ignored, it will be supplemented with 01:
* 2015 -> 2015-01-01
* 2015-07 -> 2015-07-01
* 2015-7 -> 2015-07-01
* 2015-7-5 -> 2015-07-05
Time HH:MM:SS This is not converted to UTC.
Date and time YYYY-MM-DDTHH:MM:SSZ Supports the ISO 8601 date-time format in UTC.
  • Example response: 22nd January 2021 07:00 PST is responded as "2021-01-22T15:00:00Z".
  • Example request: "2021-01-22T07:23:00Z" is treated as 22nd January 2021 07:23 PST


When using the REST APIs, an authorization header will be required.
There are two main ways to authenticate when using REST APIs.
Using password authentication allows the use of REST APIs with user-level permission, meaning that the authenticated user will need to have permission to control the App or space for the API to succeed. The other option is using API tokens to manipulate Apps with REST APIs. Each App in Kintone can create API tokens that will work specifically with that App. Other authentication methods, session authentication and OAuth authentication will also be briefly discussed.

Password authentication

X-Cybozu-Authorization is placed in the request header with a BASE64 encoded login name and password. BASE64 encode is done in the following format: Log_in_name:password.

For example, for a login name of "kintone" and a password of "developer", BASE64 encode "kintone:developer" and add this to the header:

X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=

API token authentication

Each App in Kintone can generate API tokens through the Advanced Settings in the App's settings menu. Refer to the Generating an API Token article from the Kintone Help for information on generating API tokens from an App.

X-Cybozu-API-Token is placed in the request header with the API Token. If the generated API token of the app is "9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ", add the following to the header:

X-Cybozu-API-Token: 9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ

Multiple API Tokens may be used in the case of performing REST API operations involving Lookup fields or Related Record fields. Specify the API Tokens in the header like so, with a comma in between:

X-Cybozu-API-Token: 9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ, 

The same effect may also be achieved by writing the API Tokens in two separate headers.

Session authentication

Session authentication is a method of authentication where a session ID is assigned to a user by the web server, and saved as a cookie. This cookie is used to identify and authenticate the user.

Authentication priority

The priority of authentication is as follows.

  1. Password authentication
  2. API Token authentication
  3. Session authentication

Guest users running API calls will only be able to use session authentication. They cannot use password authentication.

OAuth clients may also be used for authentication. Refer to How to Add OAuth Clients for more information.

Basic authentication

  • Kintone environments using basic authentication will need an additional authorization header. Add "Basic" followed by a BASE64 encoded "Basic_log_in_name:Password".
  • Note that initiating REST APIs for Apps in guest spaces will not need a header for basic authentication, as basic authentication itself cannot be used for guest spaces.

If the basic authentication log in name is "chocolate" and the password is "pudding", BASE64 encode "chocolate:pudding" and add this to the header:

Authorization:Basic Y2hvY29sYXRlOnB1ZGRpbmc=

* Domains created after the September 6, 2019 update are unable to use basic authentication.

Refer to the API Updates for September 2019 for details.

Request headers

These request headers are used for the REST API.

Host {subdomain}
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.
  • The X-HTTP-Method-Override header will only be valid during a POST request.
  • All REST APIs can be called when using X-HTTP-Method-Override.
  • The HTTP method specified for X-HTTP-Method-Override is case sensitive.

*This header is used to work around the Request URI Too Large error that occurs when the request URI exceeds 8KB.
*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.json
  X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
  Content-Type: application/json
  X-HTTP-Method-Override: GET

Request Body

Request URI

General https://{subdomain}{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}{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.


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.

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.

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().



  • 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:
    • The Field Mappings targets of the Lookup field
    • Categories
    • Status (this field can now be updated)
    • Assignee (this field can now be updated)
    • Calculated
  • 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.
Was this article helpful?
2 out of 3 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!