Skip to main content

upsertToolRecord

Saves a tenant-scoped JSON record into the Tools store.

Each record belongs to a collection (e.g. freight_booking). If recordId is omitted, a fresh UUID is generated and a new record is created. If recordId references an existing record in the same collection, its payload, metadata, and schemaVersion are replaced.

On create, the collection's configured notification (if any) is dispatched. Notification config (channel + target + title) lives on the tool_collections row.

Business Rules​

  • collection must be a registered, non-archived row in tool_collections
  • payload is required; the combined serialized size of payload + metadata must be ≤ the per-collection cap (default 64 KiB)
  • A record cannot move between collections
  • An existing recordId must belong to the caller's company

Error Scenarios​

  • **BAD_REQUEST**: when collection is unregistered, or payload is empty or too large
  • **NOT_FOUND**: when recordId resolves to a record owned by another company
  • **FORBIDDEN**: when caller lacks tools:save_record

Permissions Required​

  • tools:save_record
upsertToolRecord(
  input: UpsertToolRecordInput!
): ToolRecord!

Arguments​

upsertToolRecord.input ● UpsertToolRecordInput! non-null input common​

Parameters for UpsertToolRecord

Type​

ToolRecord object common​

A single tenant-scoped JSON record persisted via the Tools API. Each record belongs to a collection (a stable namespace) and carries a payload plus optional metadata.