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

1
2
3
4
5
curl -X POST https://sample.kintone.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": "Updated_datetime > \"2024-08-03T09:00:00Z\"" }'
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:

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

1
/k/v1/records.json?app=1&query=Updated_datetime+%3E+2024-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. For more information, refer to the following article:
Get Records

  1. fields=[Record_Id,Dropdown] is decomposed into separate elements:

    1
    
    /k/v1/records.json?app=1&fields[0]=Record_Id&fields[1]=Dropdown
  2. 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
1
2
3
4
5
{
  "message": "Invalid JSON string.",
  "id": "1505999166-897850006",
  "code": "CB_IJ01"
}

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 (External link)
  • 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 (External link)
  • 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 (External link)

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 (External link)

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 (External link)

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