kintone_integration

Author: r3-yamauchi
Version: 0.2.0
Type: tool

Description

This is an unofficial plugin for interacting with kintone apps. By using this plugin, you can easily access and manage the information stored in your kintone app. The source code of this plugin is available in the GitHub repository.

⚠️ Note: This is an unofficial plugin
This plugin is not developed or maintained by Cybozu, the provider of kintone. It is a community-developed plugin created by independent developers. Use at your own discretion.

Features

Retrieve records by specifying the kintone domain and app ID
Fetch field definitions by specifying the kintone domain and app ID
Obtain the reference text for the kintone query syntax
Flatten raw kintone record JSON with the tool.
Add a single record by specifying the kintone domain and app ID
Retrieve the syntax reference
Validate with a dedicated tool before adding records
Post comments to an existing record with optional mentions
Retrieve comments of a record by specifying the record ID (auto-pagination supported)
Upsert (bulk insert/update) multiple records by specifying the kintone domain and app ID
Build kintone upsert payloads from a JSON string or array input with automatic
Build kintone subtable rows ( array) from a JSON string or array input
Download files from kintone
Upload files received by Dify to kintone and obtain the fileKey

Prerequisites

An API token with appropriate permissions for the target kintone app:
- View permissions for retrieving records
- Add permissions for adding new records
- Update permissions for updating existing records

Configuration

In the provider settings, you can supply values for and . The token accepts up to nine comma-separated entries (e.g., ); providing ten or more triggers a validation error.
Each tool also allows you to specify an API token. When left unset, the provider-level token is used; when provided, the tool-level value takes precedence.

Usage Examples

1. kintone Query

1. Retrieve all records in the specified kintone app

2. Retrieve only records where is 100 or greater

3. Retrieve only the specified fields

Optional parameter: specify (seconds) to adjust the API timeout (default 30 seconds).

You can also use the optional parameter to choose the response format.

Value	Behavior
(default)	Returns text and JSON together.
	Returns only text.
	Streams JSON page-by-page (no text).
	Returns kintone records flattened into an array of plain objects.

A typical response looks like:

2. kintone Get Fields

1. Retrieve basic field definitions for the target app

Returns basic information such as field codes and field types. Information about related records is not included.

2. Retrieve the full field definitions

When is , the tool returns the complete field definition as provided by kintone. When omitted or set to , only the primary information is returned.

3. kintone Query Docs

1. Retrieve the bundled documentation for the query syntax

Returns documentation explaining the kintone query syntax.

4. kintone Flatten JSON

Convert the raw record array (typically the JSON returned by ) into flattened objects.

1. Flatten the entire record array

Response (text output mirrors the JSON message):

2. Extract a specific subtable with a field filter

Response:

limits the output to the specified SUBTABLE rows, while (comma separated) keeps only the requested field codes and copies parent-level fields into each subtable row.

5. kintone Add Record

1. Add a single new record

Optional parameter: specify (seconds) to adjust the API timeout (default 10 seconds).

6. kintone Update Record

Update one existing record. If the target record does not exist, the call fails.
If you need upsert behavior (insert when not found), use instead.

There are three example patterns; in all of them, uses the same structure as and only the specified fields are updated.

When you specify

When you specify in format

When you provide only the field code in and the value via

Specify either or . For , you may use pattern 2) or 3).
Optional parameter: (seconds) sets the timeout for the update request (default 30 seconds).

7. kintone Record Data Docs

Returns a JSON syntax guide for used by or . No parameters are required. The response contains sample structures, rules by field type, validation rules, and common errors.

8. kintone Validate Record Data

Validates the JSON string you will pass to or , against the field definitions of the app.

If the structure and types pass validation, the tool returns the formatted JSON as-is. If validation fails—for example, when a field specified in does not exist in the target app—the tool returns a message with detailed error information.

9. kintone Add Record Comment

1. Post a comment to an existing record

The tool posts plain-text comments to the record’s discussion thread. accepts up to 10,000 characters. Use the optional parameter to highlight users, groups, or departments by supplying a JSON array with objects such as . Supported values are , , and . Up to ten mentions can be specified per comment.

When the call succeeds, the response includes:

variable with the raw JSON from kintone (creator info, timestamps, etc.)
message summarizing , , , , and

Optional parameter: (seconds) to override the default 10-second timeout.

10. kintone Get Record Comments

Fetch comments posted on a record by specifying its record ID. If you leave empty and at the default 0, all comments for the record are retrieved.

1. Fetch all comments in ascending comment ID order

2. Fetch only the latest 15 comments (descending)

11. kintone Upsert Records

1. Add multiple records at once

2. Update existing records using

12. kintone Build Records Data

Convert a JSON string or array of objects into the payload expected by , automatically populating the .

Response example:

13. kintone Build Subtable Rows

Transform a JSON string or array into the array required by a kintone subtable field.

Response example:

You can also submit an array directly:

14. kintone Download File

1. Download a file from kintone by specifying the file key

How to obtain the file key

Use the tool to retrieve records that include the attachment field.
Check the attachment field in the response (for example: ).
Pass the value to the parameter of this tool.

15. kintone Upload File

1. Upload attachments and obtain file keys

Specify one or more files via . Dify automatically supplies the file data, so you do not need to provide it in JSON. You can optionally specify .

The response always contains the variable, a list of objects that hold the returned values.

Single file example:
Multiple files example:

Standard outputs are populated as follows:

: when is omitted, it contains ; when provided, it contains so you can pass it straight to .
: mirrors the JSON payload above (either the uploaded-files list or the JSON string).
/ variable messages continue to be emitted for backward compatibility.

Key parameters:

(required, files): one or more files to upload.
(optional, string or JSON array): overrides the filenames sent to kintone. Provide a string for a single file, or a JSON array (e.g. ) with the same length as the number of files.
(optional, string or JSON object): supply mapping instructions to auto-build the payload for (see below).
(optional, number): timeout in seconds for the kintone API request (default 30 seconds).

When is supplied, the tool also outputs , a JSON string that can be passed directly to .

If you provide , you can override the filenames sent to kintone. Supply a single string for one file, or a JSON array (for example ) with the same number of entries as the files you upload.

expects a JSON object with a array. Each element must include an (string) and optional kintone fields under plus any . How file keys are assigned is determined by the length of :

If has 1 item, all uploaded files are attached to that single record.
If length equals the number of uploaded files, the tool assigns files one-to-one in order.

Practical examples:

Attach all files to one record with updateKey

Distribute files one-by-one across multiple records (upload 2 files -> define 2 records)

Add extra fields per record while distributing files one-to-one

Rules summary: must be a non-empty array. Every element needs ; defaults to if omitted. With multiple records, the array length must equal the uploaded file count so each record gets exactly one file key.

Upsert behavior: when is provided, kintone will update the matching record or insert a new one if no match is found (upsert). If you omit , each entry is treated as a new record insert.

If you prefer not to use , you can build manually with standard Dify nodes:

for-each node – iterate over and capture each (alongside any known information such as record IDs). Example:
Template node (JSON mode) – compose the final payload by inserting the collected file keys into the attachment field structure () required by .
Template or “Collection → Template” – optionally use a Collection node to gather file keys or update keys into arrays before the final template step if you want to aggregate multiple keys into one record.
kintone_upsert_records – pass the template output as .

This loop + template pattern lets you control how file keys are grouped across records—for example, gather all keys and attach them to a single record, or map each key to a different record using the loop index—without enabling .

If you prefer a Python script node, you can assemble the payload in code and emit directly. The snippet below reads from the JSON output and writes back a JSON string:

Using bypasses all of these extra nodes/scripts so the workflow can simply be by selecting for the parameter (or if you prefer the raw JSON string).

Privacy Policy

The kintone_integration plugin respects user privacy and keeps the exchanged data limited to what is strictly necessary for each tool.

Data Collection

kintone credentials: Each tool requires a kintone domain, app ID, and at least one API token with the appropriate permissions (view/add/update/upload/download). These values are supplied by you or your workspace administrator.
Record payloads: Tools that create or update records receive the JSON payloads (, , , etc.) that you provide.
Query parameters: Search tools receive the query string, optional field lists, pagination controls, and timeout values you enter.
File content: The upload/download tools may handle file binaries that you submit or retrieve from kintone.
No additional identifiers: The plugin does not collect personal information beyond what is present inside the payloads you explicitly pass in.

Data Usage

kintone REST API only: All collected inputs are sent exclusively to the official kintone REST endpoints (records, file upload/download, etc.) in order to fulfill your requested action (query, validate, add, upsert, upload, or download data).
Transient processing: Record payloads, query results, and file streams are processed in memory and relayed back through Dify. They are not repurposed for analytics or profiling.
Logging: Operational logs intentionally mask API tokens and truncate oversized values to avoid leaking sensitive data.

Data Storage

No permanent storage: The plugin itself does not write any credentials, record content, or files to disk or an external database.
Platform handling: Credentials you configure are kept within Dify’s secure credential store. Uploaded files flow directly from Dify to kintone and are not retained after the request completes.
Result retention: Any responses are streamed back to Dify and handled according to your workspace’s retention settings.

Third-party Services

The plugin communicates only with kintone’s official API servers ( domains).
No other third-party processors or analytics services are used.

Security

All outbound requests use HTTPS and the standard kintone authentication headers.
API tokens are masked in logs, and error messages redact potentially sensitive details.
The plugin keeps dependencies minimal and relies on Dify’s runtime isolation for additional protection.

All plugin operations—record queries, validation, creation/upsert, and file upload/download—use kintone's official REST APIs. For kintone-side privacy policies, please refer to: cybozu.com Terms of Use.

For privacy-related questions, please contact the repository maintainers via GitHub issues.

Support

If you encounter any issues or have questions, please:

Raise an issue on the GitHub repository
Contact the plugin author

"kintone" is a registered trademark of Cybozu, Inc.

The information provided here is for reference only. Support is not available for individual environments. We are unable to respond to inquiries about configuration details or cases where the plugin does not work in your environment.