API Docs

Bulk Request

Runs multiple API requests sequentially to multiple Apps.

MethodPOST
URLhttps://{subdomain}.kintone.com/k/v1/bulkRequest.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/bulkRequest.json
Authentication Password Authentication , API Token Authentication , Session Authentication
Content-Typeapplication/json

Contents

Permissions

Permissions depend on the APIs being used.

Introduction

The Bulk Request API allows multiple API requests to run on multiple Kintone apps. The below APIs can be used with the Bulk Request API:

  • Add Record
  • Add Records
  • Update Record
  • Update Records
  • Delete Records
  • Update Status
  • Update Statuses
  • Update Assignees

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
requests Array Yes An array of requests. The maximum number of requests is 20.
requests[].method String Yes The API method for the request.
requests[].api String Yes The path of the API for the request.
requests[].payload Object Yes The parameters to be passed onto the API of the request.
Contents and formats will change depending on the API.

Sample Request

JavaScript using kintone.api() 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

var body = {
  'requests': [
    {
      'method': 'POST',
      'api': '/k/v1/record.json',
      'payload': {
        'app': 1,
        'record': {
          'text': {
            'value': 'post bulk'
          }
        }
      }
    },
    {
      'method': 'PUT',
      'api': '/k/v1/record.json',
      'payload': {
        'app': 1,
        'id': 3,
        'record': {
          'text': {
            'value': 'update bulk'
          }
        }
      }
    },
    {
      'method': 'DELETE',
      'api': '/k/v1/records.json',
      'payload': {
        'app': 1,
        'ids': [
          2
        ],
      }
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/bulkRequest.json', true), 'POST', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

curl -X POST 'https://{subdomain}.kintone.com/k/v1/bulkRequest.json' \
  -H 'X-Cybozu-API-Token: L08xCvTh7A1EVm3rZimF98R8VLP3k4lMlzELqyCx' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "method": "POST",
        "api": "/k/v1/record.json",
        "payload": {
          "app": 1,
          "record": {
            "text": {
              "value": "post bulk"
            }
          }
        }
      },
      {
        "method": "PUT",
        "api": "/k/v1/record.json",
        "payload": {
          "app": 1,
          "id": 3,
          "record": {
            "text": {
              "value": "update bulk"
            }
          }
        }
      },
      {
        "method": "DELETE",
        "api": "/k/v1/records.json",
        "payload": {
          "app": 1,
          "ids": [
            2
          ]
        }
      }
    ]
  }'

Response Parameters

An array is responded, where the results are placed into the same index as the request.

PARAMETER VALUE DESCRIPTION
results Array The response from each API request. The order of the response is the same as the order of the requests.
If an API request fails, an error will be included in the index of the failed API. In this case, all other indexes will be responded with {} (empty objects).

Sample Response

Successful Response 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "results": [
    {
      "id": "4",
      "revision": "1"
    },
    {
      "revision": "2"
    },
    {}
  ]
}

Failed Response

This is a sample failed response, where the second PUT request fails due to a record ID not existing. If an API fails the error will be responded in that index, and other indexes will respond with empty objects {}.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "results": [
    {},
    {
      "message": "Record(id:3)NotFound.",
      "id": "1505999166-1721668264",
      "code": "GAIA_RE01"
    },
    {}
  ]
}

Limitations

  • The maximum number of requests is 20.
  • If one of the API requests fail, all operations will roll back.
  • The Bulk Request API used for Guest Space apps can only target Apps within the same Guest Space.
  • When using API token authentication for operating multiple apps, specify the API token issued for each app. For information on how to specify multiple API tokens, refer to the following document:
    API token authentication