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

Values for fields inside "Date", "Time" and "Date and time" (this also includes "Created datetime and "Updated datetime") are to be written in 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:SS Note that this is not converted to UTC.
Date and time When retrieving data YYYY-MM-DDTHH:MM:SSZ

The "T" between the "YYYY-MM-DD" and the "HH:MM:SS" is a fixed value.

The "Z" after the "HH:MM:SS" is a fixed value.

The "Z" denotes that the retrieved time is in UTC time zone.

The Get Record List API responds with Date and time in UTC time zone.

As an example, 22nd January 2015 07:00 PST will be "2015-01-22T15:00:00Z".

If the string from "T" is omitted, the time will be treated as UTC.

When adding/updating data YYYY-MM-DDTHH:MM:SS±HH:MM or YYYY-MM-DDTHH:MM:SSZ

The "T" between the "YYYY-MM-DD" and the "HH:MM:SS" is a fixed value.

The "Z" after the "HH:MM:SS" is a fixed value.

The "±HH:MM" is the time difference with UTC.

As an example, 22nd January 2015 07:23 PST will be "2015-01-22T15:07:00-08:00" or "2015-01-22T23:07:00Z"

If the string from "T" is omitted, the time will be treated as UTC.

User Authentication

When using the REST APIs, an authorization header will be required.
There are two ways to authenticate when using REST APIs.
Using password authentication allows you to use 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.
Otherwise, you can use API tokens to manipulate apps with REST APIs. Each app in kintone can create API tokens that will work specifically with that app.

Password Authentication

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

If your log in name is "kintone" and your password is "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 (up to 20) through the Advanced Settings in the app's settings menu.
"X-Cybozu-API-Token" is placed in the request header with the API Token.
REST APIs initiated with API Tokens will be recorded in kintone as operations done by the user named "Administrator".
Note that "X-Cybozu-Authorization" will be prioritized over this Authentication.

REST APIs initiated through API tokens can do the following:

  • create/retrieve/update/delete app records
    *values of Lookup fields cannot be created/updated with REST API
  • use the Get Form API
  • upload and download files

If the generated API token of your app is "9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ", add this to the header:

X-Cybozu-API-Token:9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ

Basic Authentication

If your kintone environment is using basic authentication, another authorization header will need to be added. 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 your password is "pudding", BASE64 encode "chocolate:pudding" and add this to the header:

Authorization:Basic Y2hvY29sYXRlOnB1ZGRpbmc=

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

*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
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json
X-HTTP-Method-Override: GET

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

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.

Notes

New fields and keys may be added to the JSON format of request and response data after kintone updates.

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 records at once is 10.
  • The concurrency API request limit is 100.
  • If the Get Record API specifies a field code name that does not exist, nothing will be retrieved.
  • 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?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.