kintone

Programmatic access to the Cybozu kintone platform — query records, manage apps, automate workflows, and handle bulk data operations.

Prerequisites

• Node.js 18+ (for native fetch support)
• A kintone domain such as mycompany.cybozu.com, mycompany.cybozu.cn, or mycompany.kintone.com
• An API token or username/password credentials

Environment Setup

This skill needs KINTONE_BASE_URL plus one authentication method:

• Preferred: KINTONE_API_TOKEN
• Alternative: KINTONE_USERNAME + KINTONE_PASSWORD

Authentication strategy

Choose the authentication method based on the user's scope:

• Use KINTONE_API_TOKEN when the user is working with one specific app, or a known set of apps that already have API tokens.
• KINTONE_API_TOKEN may contain multiple app tokens as a comma-separated string such as token-app-a,token-app-b. This script passes that value directly to the X-Cybozu-API-Token header, so multi-app token auth is supported as long as kintone accepts those tokens for the target app.
• Use KINTONE_USERNAME + KINTONE_PASSWORD when the user wants to search, inspect, or operate across any apps that the account can access.
• Explain the tradeoff clearly: password auth usually reaches more apps, but it also grants the full permissions of that user account and therefore carries higher risk.
• If the user only needs to operate on a specified app or a small fixed set of apps, prefer API tokens.

Supported domains

This skill supports the standard kintone hosted domains:

• https://<subdomain>.cybozu.com
• https://<subdomain>.cybozu.cn
• https://<subdomain>.kintone.com

The script uses the supplied KINTONE_BASE_URL and appends the normal REST API path prefixes:

• Standard apps: /k/v1/...
• Guest spaces: /k/guest/{spaceId}/v1/...

Security notes

• Only use KINTONE_BASE_URL values that point to an official kintone hosted domain ending in .cybozu.com, .cybozu.cn, or .kintone.com.
• Treat authentication as proportional to scope: use KINTONE_API_TOKEN for specific apps whenever possible, and use KINTONE_USERNAME + KINTONE_PASSWORD only when the user truly needs broader app discovery or cross-app access.
• Never send kintone credentials or record data to third-party domains. This skill is intended to talk only to the configured kintone site.
• Only read or upload files when the user explicitly asks for records import or files upload and gives a concrete file path.

OpenClaw / ClawHub configuration

If you install this skill through OpenClaw or ClawHub, configure it in ~/.openclaw/openclaw.json:

{
  skills: {
    entries: {
      kintone: {
        enabled: true,
        env: {
          KINTONE_BASE_URL: "https://mycompany.kintone.com",
          KINTONE_API_TOKEN: "your-api-token-here",
        },
      },
    },
  },
}

If you prefer password authentication instead of an API token:

{
  skills: {
    entries: {
      kintone: {
        enabled: true,
        env: {
          KINTONE_BASE_URL: "https://mycompany.kintone.com",
          KINTONE_USERNAME: "user@example.com",
          KINTONE_PASSWORD: "your-password",
        },
      },
    },
  },
}

primaryEnv is set to KINTONE_API_TOKEN, so OpenClaw can treat token auth as the default secret for this skill. Use the env block when you need username/password instead.

Shell environment setup

If you are running the bundled CLI manually outside OpenClaw, export these variables in your shell:

# Required base URL
export KINTONE_BASE_URL="https://mycompany.kintone.com"

# Preferred authentication
export KINTONE_API_TOKEN="your-api-token-here"

# Alternative: password auth (grants broader access)
export KINTONE_USERNAME="user@example.com"
export KINTONE_PASSWORD="your-password"

API tokens are scoped per-app and recommended for production use. Generate them in each app's Settings -> API Token. For multi-app access, comma-separate tokens: KINTONE_API_TOKEN="token1,token2".

🤖 AI Assistant Guidelines (How to Handle User Requests)

Language handling

• Understand and handle user requests in Japanese, English, and Chinese.
• Reply in the user's language unless they ask you to switch languages.
• Keep kintone field codes, option values, and app names exactly as they exist in the target environment. Do not translate actual field codes or workflow action names unless the user explicitly asks for explanation.
• Recognize that different regions may use different domain suffixes, UI languages, field labels, and app names. Do not assume Japanese-only deployments.
• Never read unrelated local secrets or arbitrary files. Only use files the user explicitly names for import or upload tasks.

Users will rarely provide App IDs or exact field names (e.g., "Add a leave request for tomorrow"). When handling natural language requests, you MUST follow this interaction pattern:

1. Find the App: If the App ID isn't provided, use apps list or apps list --name "Keyword" to find the most likely app based on the user's intent. Do not guess App IDs.
2. Inspect the Schema: ALWAYS run apps fields --app <ID> to understand the app's structure, identify required fields, and see the exact field codes and types.
3. Map the Data: Map the user's natural language input (e.g., "tomorrow") to the strict field formats required by kintone (e.g., 2026-03-12 for DATE fields).
4. Ask for Missing Info: If the schema has required: true fields that the user didn't provide, stop and ask the user for that specific information.
5. Execute and Verify: Execute the command (e.g., records create). If an error occurs (e.g., validation error CB_VA01), read the error, adjust your payload, and retry. Tell the user when successful.

Bundled Script Usage

All operations use the bundled script at scripts/kintone-api.mjs. Run it with:

node <skill-path>/scripts/kintone-api.mjs <command> <sub-command> [options]

Add --json to any command for machine-readable JSON output. Add --guest-space-id <ID> for guest space operations.

Records

Query Records

# List all records from app 1
node <skill>/scripts/kintone-api.mjs records get --app 1

# With kintone query filter
node <skill>/scripts/kintone-api.mjs records get --app 1 \
  --query 'ステータス = "商談中" and 売上見込 > 1000000 order by 最終連絡 desc'

# Limit results
node <skill>/scripts/kintone-api.mjs records get --app 1 --limit 10

# Select specific fields
node <skill>/scripts/kintone-api.mjs records get --app 1 --fields "会社名,担当者,ステータス"

# JSON output for parsing
node <skill>/scripts/kintone-api.mjs records get --app 1 --json

Auto-paginates automatically (kintone returns max 500 records per request).

Get Single Record

node <skill>/scripts/kintone-api.mjs records get-one --app 1 --id 42

Create Record

node <skill>/scripts/kintone-api.mjs records create --app 1 \
  --data '{"会社名": "New Corp", "担当者": "石原", "ステータス": "初回接触"}'

Values are automatically wrapped in kintone's {"value": ...} format.

Update Record

node <skill>/scripts/kintone-api.mjs records update --app 1 --id 42 \
  --data '{"ステータス": "受注", "売上見込": 5800000}'

# With optimistic locking
node <skill>/scripts/kintone-api.mjs records update --app 1 --id 42 \
  --data '{"ステータス": "受注"}' --revision 14

Delete Records

node <skill>/scripts/kintone-api.mjs records delete --app 1 --ids "100,101,102"

Bulk Update

Update all records matching a query:

# Preview (no --yes flag)
node <skill>/scripts/kintone-api.mjs records bulk-update --app 1 \
  --query 'ステータス = "初回接触" and 最終連絡 < "2025-12-01"' \
  --set '{"ステータス": "休眠"}'

# Execute
node <skill>/scripts/kintone-api.mjs records bulk-update --app 1 \
  --query 'ステータス = "初回接触" and 最終連絡 < "2025-12-01"' \
  --set '{"ステータス": "休眠"}' --yes

Automatically chunks into 100-record batches.

Export / Import

Export to CSV

# Export to file (UTF-8 with BOM for Excel compatibility)
node <skill>/scripts/kintone-api.mjs records export --app 1 --output ./export.csv

# Export with filter
node <skill>/scripts/kintone-api.mjs records export --app 1 \
  --query 'ステータス != "休眠"' --output ./active_customers.csv

# Export as JSON
node <skill>/scripts/kintone-api.mjs records export --app 1 --json

Uses the Cursor API for efficient large dataset exports.

Import from CSV

node <skill>/scripts/kintone-api.mjs records import --app 1 --file ./data.csv

CSV must have a header row with field codes matching the app schema.

Apps

List Apps

node <skill>/scripts/kintone-api.mjs apps list
node <skill>/scripts/kintone-api.mjs apps list --name "顧客"

Get App Details

node <skill>/scripts/kintone-api.mjs apps get --app 1

View Field Schema

node <skill>/scripts/kintone-api.mjs apps fields --app 1
# Preview (uncommitted changes)
node <skill>/scripts/kintone-api.mjs apps fields --app 1 --preview

Always inspect fields before creating or updating records to understand the schema, required fields, and correct field codes. Never guess field codes.

View Form Layout

node <skill>/scripts/kintone-api.mjs apps layout --app 1

View Custom Views

node <skill>/scripts/kintone-api.mjs apps views --app 1

Create App

node <skill>/scripts/kintone-api.mjs apps create --name "新しいアプリ"
node <skill>/scripts/kintone-api.mjs apps create --name "チームアプリ" --space 5

Creates in preview mode. Use apps deploy to deploy to production.

Deploy / Check Deploy Status

node <skill>/scripts/kintone-api.mjs apps deploy --app 1
node <skill>/scripts/kintone-api.mjs apps deploy-status --app 1

Workflow (Process Management)

Update Record Status

node <skill>/scripts/kintone-api.mjs workflow status --app 5 --id 301 --action "承認"

Bulk Status Update

node <skill>/scripts/kintone-api.mjs workflow bulk-status --app 5 \
  --data '[{"id": 301, "action": "承認"}, {"id": 302, "action": "承認"}]'

Update Assignees

node <skill>/scripts/kintone-api.mjs workflow assignee --app 5 --id 301 \
  --assignees "user1,user2"

Comments

# Get comments
node <skill>/scripts/kintone-api.mjs comments get --app 1 --id 42

# Add comment (with optional @mentions)
node <skill>/scripts/kintone-api.mjs comments add --app 1 --id 42 \
  --text "確認しました" --mention "tanaka,sato"

# Delete comment
node <skill>/scripts/kintone-api.mjs comments delete --app 1 --id 42 --comment-id 5

Files

Upload

node <skill>/scripts/kintone-api.mjs files upload --file ./document.pdf
# Returns fileKey — use it to attach to a record's FILE field

Download

node <skill>/scripts/kintone-api.mjs files download \
  --file-key "20260301xxxx" --output ./downloaded.pdf

Workflow for attaching a file to a record:

1. Upload the file → get fileKey
2. Update the record's FILE field: --data '{"添付ファイル": [{"fileKey": "xxx"}]}'

Spaces

# Get space details
node <skill>/scripts/kintone-api.mjs space get --id 1

# Get space members
node <skill>/scripts/kintone-api.mjs space members --id 1

Generic API Call

For any API endpoint not covered by specific commands, use the generic api command:

# GET request
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/settings.json" --data '{"app": 1}'

# PUT request (update app settings)
node <skill>/scripts/kintone-api.mjs api \
  --method PUT --path "preview/app/settings.json" \
  --data '{"app": 1, "name": "New Name"}'

# Manage permissions
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/acl.json" --data '{"app": 1}'

# Notification settings
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "app/notifications/general.json" --data '{"app": 1}'

# Plugin management
node <skill>/scripts/kintone-api.mjs api \
  --method GET --path "plugins.json"

This provides full coverage of all kintone REST API endpoints. Refer to references/api-endpoints.md for the complete endpoint list with parameters.

kintone Query Syntax

kintone uses its own query language. Key syntax:

field_code operator "value" [and|or] field_code operator "value" [order by field_code asc|desc] [limit N] [offset N]

Operators: =, !=, >, <, >=, <=, in, not in, like, not like

Examples:

ステータス = "商談中"
会社名 like "Tech" and 売上見込 > 1000000
ステータス in ("商談中", "提案済") and 担当者 in (LOGINUSER())
作成日時 > "2026-01-01T00:00:00Z"
order by 更新日時 desc limit 100

Functions: LOGINUSER(), PRIMARY_ORGANIZATION(), NOW(), TODAY(), THIS_MONTH(), LAST_MONTH(), THIS_YEAR()

Refer to references/query-syntax.md for the complete syntax guide.

Field Types

kintone has specific value formats per field type:

Subtable format:

[{"value": {"品名": {"value": "Widget"}, "数量": {"value": "10"}}}]

Refer to references/field-types.md for the complete type reference.

Error Handling

Best Practices

1. Always inspect schema first — Run apps fields --app <ID> before creating or updating records.
2. Use --json for parsing — When processing results programmatically, always use --json output.
3. Preview before bulk — Run bulk-update without --yes first to see the preview count.
4. Respect rate limits — kintone limits concurrent connections (typically 10 per domain).
5. Use revision for updates — Include --revision on critical updates to prevent overwrite conflicts.
6. API tokens per app — Each token only grants access to its specific app. Use comma-separated tokens for multi-app.