List catalog bookings

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

item_id?string

Filter by catalog item

user_id?string

Filter by end-user id

status?string

Filter by status (hold|confirmed|cancelled|expired)

limit?integer

Default100

Formatint64

Range1 <= value <= 500

offset?integer

Default0

Formatint64

Range0 <= value

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/bookings"

{
  "$schema": "/api/v1/schemas/CatalogListBookingsOutputBody.json",
  "bookings": [
    {
      "$schema": "/api/v1/schemas/CatalogBooking.json",
      "agent_id": "string",
      "booking_id": "string",
      "conversation_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "external_ref": "string",
      "hold_expires_at": "2019-08-24T14:15:22Z",
      "item_id": "string",
      "kind": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "project_id": "string",
      "slot_id": "string",
      "status": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "user_id": "string"
    }
  ]
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create a booking hold against a catalog item (and slot, for a viewing)

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Header Parameters

X-Agent-Id?string

ID of the agent brokering this hold, if agent-initiated.

Idempotency-Key?string

Stable retry key. Required for agent-initiated holds.

Lengthlength <= 255

X-Sonzai-Action-Confirmed?boolean

True only after the representative/customer confirms this exact booking request.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

conversation_id?string

Omnichannel conversation this booking was made in.

hold_expires_at?string

RFC3339 timestamp. Defaults to now()+24h.

item_id*string

kind?string

'viewing' (default) or 'reservation'.

metadata?

slot_id?string

Viewing slot to hold. Omit for a plain unit reservation (kind=reservation).

user_id*string

End-user identity (matches the context engine's user_id space).

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/bookings" \  -H "Content-Type: application/json" \  -d '{    "item_id": "string",    "user_id": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogBooking.json",
  "agent_id": "string",
  "booking_id": "string",
  "conversation_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "external_ref": "string",
  "hold_expires_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "kind": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "project_id": "string",
  "slot_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a catalog booking

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

bookingId*string

Catalog booking UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/bookings/string"

{
  "$schema": "/api/v1/schemas/CatalogBooking.json",
  "agent_id": "string",
  "booking_id": "string",
  "conversation_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "external_ref": "string",
  "hold_expires_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "kind": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "project_id": "string",
  "slot_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Cancel a booking

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

bookingId*string

Catalog booking UUID

Header Parameters

Idempotency-Key?string

Stable retry key for this cancellation.

Lengthlength <= 255

X-Sonzai-Action-Confirmed?boolean

True only after this exact transition is approved.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/bookings/string/cancel"

{
  "$schema": "/api/v1/schemas/CatalogBooking.json",
  "agent_id": "string",
  "booking_id": "string",
  "conversation_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "external_ref": "string",
  "hold_expires_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "kind": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "project_id": "string",
  "slot_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Confirm a booking hold

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

bookingId*string

Catalog booking UUID

Header Parameters

Idempotency-Key?string

Stable retry key for this confirmation.

Lengthlength <= 255

X-Sonzai-Action-Confirmed?boolean

True only after this exact transition is approved.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

external_ref?string

Tenant-side booking id to stamp on confirmation.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/bookings/string/confirm" \  -H "Content-Type: application/json" \  -d '{}'

{
  "$schema": "/api/v1/schemas/CatalogBooking.json",
  "agent_id": "string",
  "booking_id": "string",
  "conversation_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "external_ref": "string",
  "hold_expires_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "kind": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "project_id": "string",
  "slot_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Install a fabricated, reversible property inventory demo

Authorization

bearerClerk

AuthorizationBearer <token>

Clerk session JWT from an authenticated dashboard user. Format: Bearer eyJ....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/demo-seeds/real-estate-property-demo-v1"

{
  "$schema": "/api/v1/schemas/CatalogPropertyDemoOutputBody.json",
  "created": 0,
  "deactivated": 0,
  "fabricated": true,
  "item_ids": [
    "string"
  ],
  "preset_id": "string",
  "structured_catalog": {
    "source": {
      "id": "string",
      "is_demo": true,
      "kind": "string",
      "label": "string",
      "template_id": "string"
    },
    "view": {
      "card_fields": [
        {
          "format": "string",
          "key": "string",
          "label": "string",
          "unit": "string"
        }
      ],
      "description": "string",
      "detail_fields": [
        {
          "format": "string",
          "key": "string",
          "label": "string",
          "unit": "string"
        }
      ],
      "filter_fields": [
        {
          "key": "string",
          "label": "string",
          "options": [
            {
              "label": "string",
              "value": "string"
            }
          ]
        }
      ],
      "group_by": "string",
      "item_type": "string",
      "layout": "string",
      "plural": "string",
      "show_bookings": true,
      "show_freshness": true,
      "singular": "string",
      "title": "string"
    }
  },
  "unchanged": 0,
  "updated": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Remove the fabricated property inventory demo

Authorization

bearerClerk

AuthorizationBearer <token>

Clerk session JWT from an authenticated dashboard user. Format: Bearer eyJ....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

`application/json`

`application/problem+json`

curl -X DELETE "https://loading/api/v1/projects/string/catalog/demo-seeds/real-estate-property-demo-v1"

{
  "$schema": "/api/v1/schemas/CatalogPropertyDemoOutputBody.json",
  "created": 0,
  "deactivated": 0,
  "fabricated": true,
  "item_ids": [
    "string"
  ],
  "preset_id": "string",
  "structured_catalog": {
    "source": {
      "id": "string",
      "is_demo": true,
      "kind": "string",
      "label": "string",
      "template_id": "string"
    },
    "view": {
      "card_fields": [
        {
          "format": "string",
          "key": "string",
          "label": "string",
          "unit": "string"
        }
      ],
      "description": "string",
      "detail_fields": [
        {
          "format": "string",
          "key": "string",
          "label": "string",
          "unit": "string"
        }
      ],
      "filter_fields": [
        {
          "key": "string",
          "label": "string",
          "options": [
            {
              "label": "string",
              "value": "string"
            }
          ]
        }
      ],
      "group_by": "string",
      "item_type": "string",
      "layout": "string",
      "plural": "string",
      "show_bookings": true,
      "show_freshness": true,
      "singular": "string",
      "title": "string"
    }
  },
  "unchanged": 0,
  "updated": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Import catalog items from a CSV or XLSX file

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

item_type*string

Target item_type — a catalog_schemas entry must already exist for it

dry_run?boolean

If true, returns the proposed mapping + preview rows without writing anything

Defaultfalse

mapping?string

JSON-encoded []ColumnMapping to apply directly, skipping LLM proposal (required when dry_run=false unless a mapping was already confirmed client-side)

Request Body

multipart/form-data

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/import?item_type=string"

{
  "$schema": "/api/v1/schemas/CatalogImportOutputBody.json",
  "mapping": [
    {
      "column": "string",
      "field": "string"
    }
  ],
  "preview": [
    {
      "$schema": "/api/v1/schemas/CatalogItem.json",
      "attributes": {
        "property1": null,
        "property2": null
      },
      "created_at": "2019-08-24T14:15:22Z",
      "currency": "string",
      "description": "string",
      "external_ref": "string",
      "is_active": true,
      "item_id": "string",
      "item_type": "string",
      "kb_node_id": "string",
      "media": [
        {
          "gcs_uri": "string",
          "kb_document_id": "string",
          "kind": "string"
        }
      ],
      "name": "string",
      "parent_item_id": "string",
      "price": 0.1,
      "price_unit": "string",
      "price_updated_at": "2019-08-24T14:15:22Z",
      "project_id": "string",
      "status": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ],
  "result": {
    "$schema": "/api/v1/schemas/CatalogSyncResult.json",
    "created": 0,
    "deactivated": 0,
    "item_ids": [
      "string"
    ],
    "unchanged": 0,
    "updated": 0
  },
  "row_errors": [
    {
      "reason": "string",
      "row_index": 0
    }
  ]
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List catalog items

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

item_type?string

Filter by item_type

source_id?string

Filter by browser-safe structured source identifier

status?string

Filter by status

limit?integer

Default100

Formatint64

Range1 <= value <= 500

offset?integer

Default0

Formatint64

Range0 <= value

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/items"

{
  "$schema": "/api/v1/schemas/CatalogListItemsOutputBody.json",
  "items": [
    {
      "$schema": "/api/v1/schemas/CatalogItem.json",
      "attributes": {
        "property1": null,
        "property2": null
      },
      "created_at": "2019-08-24T14:15:22Z",
      "currency": "string",
      "description": "string",
      "external_ref": "string",
      "is_active": true,
      "item_id": "string",
      "item_type": "string",
      "kb_node_id": "string",
      "media": [
        {
          "gcs_uri": "string",
          "kb_document_id": "string",
          "kind": "string"
        }
      ],
      "name": "string",
      "parent_item_id": "string",
      "price": 0.1,
      "price_unit": "string",
      "price_updated_at": "2019-08-24T14:15:22Z",
      "project_id": "string",
      "status": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ],
  "limit": 0,
  "next_offset": 0,
  "offset": 0,
  "status_counts": {
    "property1": 0,
    "property2": 0
  },
  "total": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create a catalog item

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

attributes?

currency?string

description?string

external_ref?string

item_type*string

media?array<>|null

name*string

parent_item_id?string

price?number

Formatdouble

price_unit?string

status?string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/items" \  -H "Content-Type: application/json" \  -d '{    "item_type": "string",    "name": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogItem.json",
  "attributes": {
    "property1": null,
    "property2": null
  },
  "created_at": "2019-08-24T14:15:22Z",
  "currency": "string",
  "description": "string",
  "external_ref": "string",
  "is_active": true,
  "item_id": "string",
  "item_type": "string",
  "kb_node_id": "string",
  "media": [
    {
      "gcs_uri": "string",
      "kb_document_id": "string",
      "kind": "string"
    }
  ],
  "name": "string",
  "parent_item_id": "string",
  "price": 0.1,
  "price_unit": "string",
  "price_updated_at": "2019-08-24T14:15:22Z",
  "project_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Idempotently upsert a batch of catalog items keyed by external_ref

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Header Parameters

X-Sonzai-Catalog-Source?string

Stable source identifier; connector rows are stamped with it

X-Sonzai-Catalog-Verified-At?string

RFC3339 time when the connector completed reading this source snapshot

X-Sonzai-Catalog-Snapshot-Hash?string

Optional stable hex digest of the complete source snapshot

X-Sonzai-Catalog-Max-Age-Seconds?integer

Seconds after verification before live grounding fails closed

Formatint64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

items*array<>|null

remove_missing?boolean

Soft-deactivate active items (of the item_types in this batch) whose external_ref is absent from it

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://loading/api/v1/projects/string/catalog/items/sync" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "external_ref": "string",        "item_type": "string",        "name": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/CatalogSyncResult.json",
  "created": 0,
  "deactivated": 0,
  "item_ids": [
    "string"
  ],
  "unchanged": 0,
  "updated": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a catalog item

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/items/string"

{
  "$schema": "/api/v1/schemas/CatalogItem.json",
  "attributes": {
    "property1": null,
    "property2": null
  },
  "created_at": "2019-08-24T14:15:22Z",
  "currency": "string",
  "description": "string",
  "external_ref": "string",
  "is_active": true,
  "item_id": "string",
  "item_type": "string",
  "kb_node_id": "string",
  "media": [
    {
      "gcs_uri": "string",
      "kb_document_id": "string",
      "kind": "string"
    }
  ],
  "name": "string",
  "parent_item_id": "string",
  "price": 0.1,
  "price_unit": "string",
  "price_updated_at": "2019-08-24T14:15:22Z",
  "project_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update a catalog item

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Query Parameters

version*integer

Expected current version (optimistic concurrency)

Formatint64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

attributes?

currency?string

description?string

external_ref?string

item_type*string

media?array<>|null

name*string

parent_item_id?string

price?number

Formatdouble

price_unit?string

status?string

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://loading/api/v1/projects/string/catalog/items/string?version=0" \  -H "Content-Type: application/json" \  -d '{    "item_type": "string",    "name": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogItem.json",
  "attributes": {
    "property1": null,
    "property2": null
  },
  "created_at": "2019-08-24T14:15:22Z",
  "currency": "string",
  "description": "string",
  "external_ref": "string",
  "is_active": true,
  "item_id": "string",
  "item_type": "string",
  "kb_node_id": "string",
  "media": [
    {
      "gcs_uri": "string",
      "kb_document_id": "string",
      "kind": "string"
    }
  ],
  "name": "string",
  "parent_item_id": "string",
  "price": 0.1,
  "price_unit": "string",
  "price_updated_at": "2019-08-24T14:15:22Z",
  "project_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Deactivate a catalog item

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Response Body

`application/problem+json`

curl -X DELETE "https://loading/api/v1/projects/string/catalog/items/string"

Empty

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List an item's viewing slots

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/items/string/slots"

{
  "$schema": "/api/v1/schemas/CatalogListSlotsOutputBody.json",
  "slots": [
    {
      "$schema": "/api/v1/schemas/CatalogSlot.json",
      "booked_count": 0,
      "capacity": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "ends_at": "2019-08-24T14:15:22Z",
      "item_id": "string",
      "project_id": "string",
      "slot_id": "string",
      "starts_at": "2019-08-24T14:15:22Z",
      "status": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create a viewing slot for an item

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

capacity?integer

Formatint64

ends_at*string

RFC3339 timestamp

starts_at*string

RFC3339 timestamp

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/items/string/slots" \  -H "Content-Type: application/json" \  -d '{    "ends_at": "string",    "starts_at": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogSlot.json",
  "booked_count": 0,
  "capacity": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "ends_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "project_id": "string",
  "slot_id": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update a catalog item's status

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemId*string

Catalog item UUID

Query Parameters

version*integer

Expected current version (optimistic concurrency)

Formatint64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*string

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://loading/api/v1/projects/string/catalog/items/string/status?version=0" \  -H "Content-Type: application/json" \  -d '{    "status": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogItem.json",
  "attributes": {
    "property1": null,
    "property2": null
  },
  "created_at": "2019-08-24T14:15:22Z",
  "currency": "string",
  "description": "string",
  "external_ref": "string",
  "is_active": true,
  "item_id": "string",
  "item_type": "string",
  "kb_node_id": "string",
  "media": [
    {
      "gcs_uri": "string",
      "kb_document_id": "string",
      "kind": "string"
    }
  ],
  "name": "string",
  "parent_item_id": "string",
  "price": 0.1,
  "price_unit": "string",
  "price_updated_at": "2019-08-24T14:15:22Z",
  "project_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List catalog schemas

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/schemas"

{
  "$schema": "/api/v1/schemas/CatalogListSchemasOutputBody.json",
  "schemas": [
    {
      "$schema": "/api/v1/schemas/CatalogSchema.json",
      "created_at": "2019-08-24T14:15:22Z",
      "fields": [
        {
          "description": "string",
          "enum_values": [
            "string"
          ],
          "filterable": true,
          "key": "string",
          "required": true,
          "type": "string",
          "unit": "string"
        }
      ],
      "item_type": "string",
      "project_id": "string",
      "schema_id": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ]
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Define the attribute schema for an item_type

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields*array<>|null

item_type*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/schemas" \  -H "Content-Type: application/json" \  -d '{    "fields": [      {        "key": "string",        "type": "string"      }    ],    "item_type": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogSchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "filterable": true,
      "key": "string",
      "required": true,
      "type": "string",
      "unit": "string"
    }
  ],
  "item_type": "string",
  "project_id": "string",
  "schema_id": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Idempotently install the attribute schema for an item_type

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

itemType*string

Stable catalog item type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields*array<>|null

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://loading/api/v1/projects/string/catalog/schemas/item-types/string" \  -H "Content-Type: application/json" \  -d '{    "fields": [      {        "key": "string",        "type": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/CatalogSchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "filterable": true,
      "key": "string",
      "required": true,
      "type": "string",
      "unit": "string"
    }
  ],
  "item_type": "string",
  "project_id": "string",
  "schema_id": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a catalog schema

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

schemaId*string

Catalog schema UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/schemas/string"

{
  "$schema": "/api/v1/schemas/CatalogSchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "filterable": true,
      "key": "string",
      "required": true,
      "type": "string",
      "unit": "string"
    }
  ],
  "item_type": "string",
  "project_id": "string",
  "schema_id": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update a catalog schema's fields

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

schemaId*string

Catalog schema UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields*array<>|null

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://loading/api/v1/projects/string/catalog/schemas/string" \  -H "Content-Type: application/json" \  -d '{    "fields": [      {        "key": "string",        "type": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/CatalogSchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "filterable": true,
      "key": "string",
      "required": true,
      "type": "string",
      "unit": "string"
    }
  ],
  "item_type": "string",
  "project_id": "string",
  "schema_id": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete a catalog schema

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

schemaId*string

Catalog schema UUID

Response Body

`application/problem+json`

curl -X DELETE "https://loading/api/v1/projects/string/catalog/schemas/string"

Empty

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a catalog slot

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

slotId*string

Catalog slot UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/slots/string"

{
  "$schema": "/api/v1/schemas/CatalogSlot.json",
  "booked_count": 0,
  "capacity": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "ends_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "project_id": "string",
  "slot_id": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update a catalog slot

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

slotId*string

Catalog slot UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

capacity*integer

Formatint64

ends_at*string

starts_at*string

status*string

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://loading/api/v1/projects/string/catalog/slots/string" \  -H "Content-Type: application/json" \  -d '{    "capacity": 0,    "ends_at": "string",    "starts_at": "string",    "status": "string"  }'

{
  "$schema": "/api/v1/schemas/CatalogSlot.json",
  "booked_count": 0,
  "capacity": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "ends_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "project_id": "string",
  "slot_id": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete a catalog slot

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

slotId*string

Catalog slot UUID

Response Body

`application/problem+json`

curl -X DELETE "https://loading/api/v1/projects/string/catalog/slots/string"

Empty

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Begin or resume an authoritative catalog snapshot upload

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Header Parameters

X-Sonzai-Catalog-Source?string

Stable source identifier

X-Sonzai-Catalog-Verified-At?string

RFC3339 time when the connector completed reading the source snapshot

X-Sonzai-Catalog-Snapshot-Hash?string

Stable hex digest of the complete source snapshot

X-Sonzai-Catalog-Max-Age-Seconds?integer

Seconds after verification before grounding fails closed

Formatint64

Idempotency-Key?string

Stable retry key for this exact source snapshot

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expected_item_count*integer

Formatint64

Range0 <= value <= 100000

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/snapshots" \  -H "Content-Type: application/json" \  -d '{    "expected_item_count": 0  }'

{
  "$schema": "/api/v1/schemas/CatalogSnapshotSession.json",
  "created_at": "2019-08-24T14:15:22Z",
  "expected_item_count": 0,
  "finalized_at": "2019-08-24T14:15:22Z",
  "max_age_seconds": 0,
  "project_id": "string",
  "result": {
    "$schema": "/api/v1/schemas/CatalogSyncResult.json",
    "created": 0,
    "deactivated": 0,
    "item_ids": [
      "string"
    ],
    "unchanged": 0,
    "updated": 0
  },
  "session_id": "string",
  "snapshot_hash": "string",
  "source_id": "string",
  "status": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "verified_at": "2019-08-24T14:15:22Z"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Idempotently upload one bounded catalog snapshot chunk

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

sessionId*string

Snapshot session UUID

chunkIndex*integer

Zero-based contiguous chunk index

Formatint64

Range0 <= value

Header Parameters

X-Sonzai-Catalog-Source?string

Source identifier used to namespace item references

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

items*array<>|

Items1 <= items <= 500

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://loading/api/v1/projects/string/catalog/snapshots/string/chunks/0" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "external_ref": "string",        "item_type": "string",        "name": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/CatalogSnapshotChunkReceipt.json",
  "index": 0,
  "item_count": 0,
  "replayed": true,
  "session_id": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Atomically promote a complete authoritative catalog snapshot

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

sessionId*string

Snapshot session UUID

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/projects/string/catalog/snapshots/string/finalize"

{
  "$schema": "/api/v1/schemas/CatalogSyncResult.json",
  "created": 0,
  "deactivated": 0,
  "item_ids": [
    "string"
  ],
  "unchanged": 0,
  "updated": 0
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Read the source's durable verification receipt

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

sourceId*string

Stable structured source identifier

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/projects/string/catalog/sources/string/state"

{
  "$schema": "/api/v1/schemas/CatalogSourceStateOutputBody.json",
  "item_count": 0,
  "last_verified_at": "2019-08-24T14:15:22Z",
  "source_id": "string",
  "stale_after": "2019-08-24T14:15:22Z",
  "status": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Catalog

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

204

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`