Kintone REST API Overview

Contents

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 Authentication.

Requests

Request headers

These request headers are used for the REST API. It is not necessary to specify request headers when using the Kintone REST API request API.

HEADER REQUIRED VALUE
Host Required {subdomain}.kintone.com:443
Content-Type Conditional For JSON: application/json or for multipart data: multipart/form-data.
Only required when sending a request body.
X-Cybozu-Authorization Conditional login_name:password encoded in base64. Only required when using Password Authentication.
X-Cybozu-API-Token Conditional The Kintone App's API Token. Only required when using API Token Authentication..
Authorization Conditional Basic followed by a Base64 encoded login_name:password. Only required when using the deprecated Basic Authentication, which is no longer available as of June 2020.
X-HTTP-Method-Override Optional 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.
* This header method is available on all Kintone REST API routes, but behavior can not be guaranteed when using with external APIs.
* 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
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json
X-HTTP-Method-Override: GET
Request Body
{
"app":"8",
"query":"date > "2015-05-03T09:00:00-0800" and date < "2015-05-03T10:00:00-0800""
}
Accept-Language Optional The Language Code, e.g.en, ja, zh, es.
Forces the data from a field to be returned in the specified language, if a localization has been set. This overrides the system locale language, and user locale language.

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

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:

/k/v1/records.json?app=1

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 > "2021-10-01T09:00:00+0900":

/k/v1/records.json?app=1&query=Updated_datetime+%3E+2021-10-01T09%3A00%3A00%2B0900

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.

  1. fields=[Record_Id,Dropdown] is decomposed into separate elements /k/v1/records.json?app=1&fields[0]=Record_Id&fields[1]=Dropdown
  2. The keys and values of each parameter are URL encoded /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 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
1
2
3
4
5
{
  "message": "Invalid JSON string.",
  "id": "1505999166-897850006",
  "code": "CB_IJ01"
}

Response Headers

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 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, don't use kintone.api() to make the requests, and use another method.

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:
  • 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 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
  • Z: Indicates that the date time is expressed in UTC.
  • T: A fixed value to separate the date from the time.
For Responses
  • Data is responded as YYYY-MM-DDTHH:MM:SSZ
  • Example: 22nd January 2021 07:00 PST will be responded as 2021-01-22T15:00:00Z.
For Requests
  • Data is requested in one of the following formats:
    • YYYY-MM-DD
    • YYYY-MM-DDTHH:MM:SSZ
    • YYYY-MM-DDTHH:MM:SS±HH:MM
  • If the date is requested as YYYY-MM-DD, it is treated as UTC
  • Values stated for SS will be ignored, and will be treated as 00
  • Example: 22nd January 2021 07:23 PST can be requested as 2021-01-22T15:23:00Z or 2021-01-22T07:23:00-08:00

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 (External link) from the Kintone Help Center for more details.
  • 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, see The number of API requests available per day (External link) .
  • If a domain has IP address restriction, only API requests from an approved IP address will be successful.

Limitations

  • 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 on limitations and usage of the Kintone REST API, please refer to the List of Limit Values (External link) REST API Section.