Folders

Update many folders

POST/folders/bulk/update
documents:writebulk_update_foldersIdempotent

Changes up to 100 folders in the request, or 101 to 10,000 as a job that answers 202 with the job. Each item is a folder id with the fields to change, as in PATCH /folders/{id}, and runs on its own: a failed item is reported in its slot and the rest carry on. Use PATCH /folders/{id} for one folder. dry_run runs up to 100 items and rolls them back. Emits folder.updated per item that succeeds, after commit, and sends no email. Sending the previous values undoes it, except permissions inherited on a move.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · FolderBulkUpdate

  • itemsobject[]Required#

    Up to 10,000 items. Each is a folder id plus the fields to change, as in FolderUpdate. Up to 100 run in the request.

{
  "items": [
    {
      "id": "3b9e5f6a-7c1d-4e2f-8a90-1b2c3d4e5f60",
      "name": "Due Diligence (Final)"
    },
    {
      "id": "4e5f6071-8293-4a4b-9c6d-7e8f90112233",
      "pinned": true
    }
  ]
}

Responses

200

Every item in request order, each succeeded or failed.

FolderBulkReport
{
  "data": [
    {
      "index": 1,
      "status": "succeeded",
      "data": {},
      "error": {}
    }
  ],
  "meta": {
    "succeeded": 1,
    "failed": 1
  }
}
202

More than 100 items. A job runs them; its report has the same shape as the 200 body.

Job
{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "type": "string",
    "status": "queued",
    "progress": {
      "done": 1,
      "total": 1
    },
    "result": {},
    "error": {},
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00",
    "completed_at": "2026-06-12T10:00:00+00:00"
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is forbidden when the token's user can't write the folder: any folder in the tree of a deal the token can see is writable, otherwise the folder's write list, write flags or super admin are needed. This is deliberately broader than the platform (no editor-role check) and stricter (the check applies where the platform skips it by role). Other codes are missing_scope, scope_disabled, org_disabled, ip_blocked, user_disabled.

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/folders/bulk/update\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "items": [
    {
      "id": "3b9e5f6a-7c1d-4e2f-8a90-1b2c3d4e5f60",
      "name": "Due Diligence (Final)"
    },
    {
      "id": "4e5f6071-8293-4a4b-9c6d-7e8f90112233",
      "pinned": true
    }
  ]
}'