Collection Blocks

Collections are dynamic "databases" in a bucket: you define a schema (properties) and add rows (items). Use these blocks to create collections, read/write items, run aggregates, and manage webhooks. bucketId comes from execution context.

Block Types Overview

Category	Block Type	Purpose
Collections CRUD	`kaizen_create_collection`	Create a collection (from template or empty).
	`kaizen_list_collections`	List all collections in the bucket.
	`kaizen_get_collection`	Get collection metadata, properties (schema), and views.
	`kaizen_update_collection`	Update collection name, description, or schema.
	`kaizen_delete_collection`	Delete a collection.
	`kaizen_duplicate_collection`	Duplicate a collection (schema and optionally data).
Items	`kaizen_get_collection_item`	Get one item (use itemId `me` for current user's item).
	`kaizen_update_collection_item`	Update an item's values (`me` creates if missing).
	`kaizen_create_collection_item`	Create a new item (row).
	`kaizen_delete_collection_item`	Delete an item (soft delete).
	`kaizen_list_collection_items`	List items with filters, sort, pagination.
	`kaizen_save_todos_to_collection`	Append selected todo IDs as one row (e.g. Selected Todo IDs template).
	`kaizen_batch_collection_items`	Run up to 100 create/update/delete operations in one request.
	`kaizen_restore_collection_item`	Restore a soft-deleted item.
	`kaizen_reorder_collection_item`	Move an item to a new display order position.
Aggregate	`kaizen_aggregate_collection`	Count, sum, avg, min, max on items (optional groupBy and filters).
Webhooks	`kaizen_list_collection_webhooks`	List webhooks for a collection.
	`kaizen_create_collection_webhook`	Create a webhook (URL + events: create, update, delete).
	`kaizen_update_collection_webhook`	Update a webhook.
	`kaizen_delete_collection_webhook`	Delete a webhook.
	`kaizen_test_collection_webhook`	Send a test payload to the webhook URL.

Setup

In the bucket, go to Collections and create a collection (e.g. "Habit log").
Add properties (columns): name, type (number, text, boolean, select, date, etc.).
Use the blocks with the collection ID (from the collection detail URL or from a Create/List/Get Collection block output).

Collections CRUD

Create Collection (`kaizen_create_collection`)

Creates a collection in the current bucket. Mode: From template (e.g. "Selected Todo IDs") or Empty. Inputs: mode, templateId (when from template), name, description. Outputs: collectionId, collection.

List Collections (`kaizen_list_collections`)

Lists all collections in the bucket. No inputs. Outputs: collections, collectionIds, success.

Get Collection (`kaizen_get_collection`)

Fetches collection metadata, properties (schema), and views. Inputs: collectionId. Outputs: collection, properties, views, success.

Update Collection (`kaizen_update_collection`)

Updates collection name, description, or schema. Inputs: collectionId, and fields to update. Outputs: collection, success.

Delete Collection (`kaizen_delete_collection`)

Deletes a collection. Inputs: collectionId. Outputs: success, message.

Duplicate Collection (`kaizen_duplicate_collection`)

Duplicates a collection (schema and optionally data). Inputs: collectionId, optional options. Outputs: collectionId, collection, success.

Items

Get Collection Item (`kaizen_get_collection_item`)

Retrieves a single item. Use itemId me to get the current user's item (where createdBy = current user).

Field	Type	Required	Description
`collectionId`	string	Yes	Collection ID
`itemId`	string	No	Item ID, or `me` for current user's item. Default: `me`

Outputs: success, item (id, collectionId, createdBy, createdAt, updatedAt, values).

Update Collection Item (`kaizen_update_collection_item`)

Updates an item's values. Use itemId me to update the current user's item; the API creates it if missing (PATCH to /items/me).

Field	Type	Required	Description
`collectionId`	string	Yes	Collection ID
`itemId`	string	No	Item ID, or `me` for current user's item. Default: `me`
`values`	object	Yes	Map of property name to value (number, boolean, string, or null)

Outputs: success, item.

Create Collection Item (`kaizen_create_collection_item`)

Creates a new item (row) in the collection.

Field	Type	Required	Description
`collectionId`	string	Yes	Collection ID
`values`	object	No	Optional initial values: property name → value

Outputs: success, item.

Delete Collection Item (`kaizen_delete_collection_item`)

Soft-deletes an item. Inputs: collectionId, itemId. Outputs: success, message. Use Restore Collection Item to undo.

List Collection Items (`kaizen_list_collection_items`)

Lists items with optional filters, sort, and pagination. Inputs: collectionId, optional filters, sort/sorts, order, createdBy, includeDeleted, orderByDisplayOrder, limit, offset. Outputs: items, total, success.

Save Todos to Collection (`kaizen_save_todos_to_collection`)

Creates one collection item with todo_ids (and optional round) from a block reference like <KaizenTodos.todoIds>. Use after Create Collection (template "Selected Todo IDs") and Kaizen Todos. Inputs: collectionId, todoIds (block reference), optional round. Outputs: success, item.

Batch Collection Items (`kaizen_batch_collection_items`)

Run up to 100 create/update/delete operations in one request. Inputs: collectionId, operations (JSON array). Each op: create { op: "create", values?, createdBy? }, update { op: "update", itemId, values }, delete { op: "delete", itemId }. Outputs: success, results (per-operation result).

Restore Collection Item (`kaizen_restore_collection_item`)

Restores a soft-deleted item. Inputs: collectionId, itemId. Outputs: success, item.

Reorder Collection Item (`kaizen_reorder_collection_item`)

Moves an item to a new display order position. Inputs: collectionId, itemId, optional beforeItemId (ID of row that will be directly above; omit to move to end). Outputs: success, item.

Aggregate Collection (`kaizen_aggregate_collection`)

Runs count, sum, avg, min, or max on collection items. Inputs: collectionId, function (count, sum, avg, min, max), property (required for sum/avg/min/max), optional groupBy, optional filters. Outputs: success, result value or grouped results.

Collection Webhooks

Webhooks notify a URL when items are created, updated, or deleted.

Block	Purpose
`kaizen_list_collection_webhooks`	List webhooks for a collection. Inputs: `collectionId`. Outputs: `webhooks`, `success`.
`kaizen_create_collection_webhook`	Create webhook. Inputs: `collectionId`, `url`, optional `events` (create, update, delete). Outputs: `webhook`, `success`.
`kaizen_update_collection_webhook`	Update webhook URL or events. Inputs: `collectionId`, `webhookId`, `url` and/or `events`. Outputs: `webhook`, `success`.
`kaizen_delete_collection_webhook`	Delete a webhook. Inputs: `collectionId`, `webhookId`. Outputs: `success`, `message`.
`kaizen_test_collection_webhook`	Send a test payload to the webhook URL. Inputs: `collectionId`, `webhookId`. Outputs: `success`, `status` (HTTP status), `message`.

Example: Per-User Habit Log

# Collection "Habit log" with properties: date (date), habit (text), done (boolean)

# Get today's log for current user
Get Collection Item:
  collectionId: "<your-collection-id>"
  itemId: "me"

# Update: set a property (e.g. after a form)
Update Collection Item:
  collectionId: "<your-collection-id>"
  itemId: "me"
  values:
    date: "2025-02-04"
    habit: "Exercise"
    done: true

# Or create a new row
Create Collection Item:
  collectionId: "<your-collection-id>"
  values:
    date: "2025-02-04"
    habit: "Read"
    done: false

When using itemId me, the bucket collection API returns or creates the single item where createdBy equals the current user, so you get one row per user for that collection.

Reference collection IDs from block outputs: e.g. <kaizen_create_collection_1.collectionId> or <kaizen_list_collections_1.collectionIds> (when iterating). Use Save Todos to Collection with a collection created from the "Selected Todo IDs" template and <KaizenTodos.todoIds> to record selected todos as rows.

Collection Blocks

On this page