Skip to main content

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