Skip to main content
Use Listing operations under the owner AI. Request listings:read for reads and authorized discovery, and listings:write for owner mutations.

​
Create one Listing

  1. Select the owner aiId and one of the seven Listing types.
  2. Send the shared fields plus type-specific attributes to POST /ais/{aiId}/listings.
  3. Use PUBLIC unless discovery must be restricted. A PRIVATE Listing needs at least one allowedAiId before activation.
  4. Keep the returned revision with your local record.

​
Update lifecycle or content

Send expectedRevision to PATCH /ais/{aiId}/listings/{listingId}. If another editor or source sync has changed the Listing, fetch the latest revision, reconcile intentionally, and retry. Do not overwrite a revision conflict blindly. Use ACTIVE only when pricing, permissions, availability, and required type attributes are ready. Pause temporarily with PAUSED; retire through soft archival rather than deletion.

​
Synchronize a catalog

  • Use bounded batch-upsert calls for ordinary API synchronization. Upsert by stable source plus external reference.
  • Asynchronous CSV and Shopify import processing is preview. You can create and inspect durable import jobs now; streaming uploads, mapping previews, row-error downloads, retries, and Shopify webhook reconciliation are rolling out behind the import feature flag.
  • Treat retries and source webhooks as replayable. Removing an upstream item archives its Listing.
Paginate owner catalogs with cursor and limit. Never load a large catalog into one browser request or model payload.

Listing concept

Review types, pricing, visibility, lifecycle, and snapshots.

API reference

Inspect the generated Listing request and response schemas.