Collections Commands
See Collections module docs for permissions and data model.
soat list-collections
List collections
- Method:
GET - Path:
/api/v1/collections
Usage
soat list-collections
Options
--project-id
Project public ID (proj_ prefix)
- Source:
query - Required: no
- Type:
string - Example:
proj_V1StGXR8Z5jdHi6B
soat create-collection
Create a collection
- Method:
POST - Path:
/api/v1/collections
Usage
soat create-collection --name <string>
Options
--project-id
Project the collection belongs to. Optional for a project-scoped API key, which supplies it.
- Source:
body - Required: no
- Type:
string - Example:
proj_V1StGXR8Z5jdHi6B
--name
Unique within the project.
- Source:
body - Required: yes
- Type:
string - Example:
support-tickets
--schema
A JSON Schema every item's data must satisfy, stored as written. null removes it.
- Source:
body - Required: no
- Type:
object - Example:
\{"type":"object","required":["status"],"properties":\{"status":\{"type":"string"\}\}\}
soat get-collection
Get a collection
- Method:
GET - Path:
/api/v1/collections/{collection_id}
Usage
soat get-collection
Options
This command has no options.
soat update-collection
Update a collection
- Method:
PATCH - Path:
/api/v1/collections/{collection_id}
Usage
soat update-collection
Options
--name
Unique within the project.
- Source:
body - Required: no
- Type:
string - Example:
support-tickets
--schema
A JSON Schema every item's data must satisfy, stored as written. null removes it.
- Source:
body - Required: no
- Type:
object - Example:
\{"type":"object","required":["status"],"properties":\{"status":\{"type":"string"\}\}\}
soat delete-collection
Delete a collection
- Method:
DELETE - Path:
/api/v1/collections/{collection_id}
Usage
soat delete-collection
Options
This command has no options.
soat list-collection-items
List items
- Method:
GET - Path:
/api/v1/collections/{collection_id}/items
Usage
soat list-collection-items
Options
This command has no options.
soat get-collection-item
Get an item
- Method:
GET - Path:
/api/v1/collections/{collection_id}/items/{key}
Usage
soat get-collection-item
Options
This command has no options.
soat put-collection-item
Create or replace an item
- Method:
PUT - Path:
/api/v1/collections/{collection_id}/items/{key}
Usage
soat put-collection-item --data <object>
Options
--data
The item's JSON object, at most 64 KB serialized. Stored as jsonb, so key order is not kept.
- Source:
body - Required: yes
- Type:
object - Example:
\{"status":"open","priority":2,"actor_id":"actor_V1StGXR8Z5jdHi6B"\}
--tags
Replaces the item's tags; null clears them.
- Source:
body - Required: no
- Type:
unknown
--expected-version
Refuses the write unless the item is at this version.
- Source:
body - Required: no
- Type:
unknown
soat update-collection-item
Update an item
- Method:
PATCH - Path:
/api/v1/collections/{collection_id}/items/{key}
Usage
soat update-collection-item
Options
--data
The merge patch applied to the item's data.
- Source:
body - Required: no
- Type:
object
--tags
Replaces the item's tags; null clears them.
- Source:
body - Required: no
- Type:
unknown
--expected-version
Refuses the write unless the item is at this version.
- Source:
body - Required: no
- Type:
unknown
soat delete-collection-item
Delete an item
- Method:
DELETE - Path:
/api/v1/collections/{collection_id}/items/{key}
Usage
soat delete-collection-item
Options
This command has no options.
soat get-collection-item-tags
Get item tags
- Method:
GET - Path:
/api/v1/collections/{collection_id}/items/{key}/tags
Usage
soat get-collection-item-tags
Options
This command has no options.
soat replace-collection-item-tags
Replace item tags
- Method:
PUT - Path:
/api/v1/collections/{collection_id}/items/{key}/tags
Usage
soat replace-collection-item-tags --tags <object>
Options
--tags
Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
- Source:
body - Required: yes
- Type:
object
soat merge-collection-item-tags
Merge item tags
- Method:
PATCH - Path:
/api/v1/collections/{collection_id}/items/{key}/tags
Usage
soat merge-collection-item-tags --tags <object>
Options
--tags
Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
- Source:
body - Required: yes
- Type:
object