Skip to main content

ApplyCatalogSync

POST 
/admin/v1/catalog/sync:apply

ApplyCatalogSync starts one background sync run and returns it RUNNING; poll GetCatalogSyncRun for progress. At most one run exists at a time -- a second apply while one is in flight fails with ALREADY_EXISTS.

The request MUST carry the sources (with sha256 digests) the preview reported. The apply re-fetches pinned to those digests, so what gets applied is byte-for-byte what the human reviewed; a published catalogue that changed in between fails the run with an instruction to re-preview rather than silently applying something nobody looked at.

Error-code contract, which a dashboard branches on (never on message text):

  • ABORTED: the preview went stale -- the source configuration changed under the reviewed pin set. Re-run PlanCatalogSync and apply again. The same verdict reached asynchronously (the published catalogue changed between preview and apply) surfaces as a FAILED run with failure_reason = STALE_CATALOG.
  • FAILED_PRECONDITION: the plane cannot sync until an operator fixes something (sources unconfigured, published catalogue malformed). Retrying as-is will not help.
  • ALREADY_EXISTS: a run is in flight; poll it.
  • INVALID_ARGUMENT: the request is missing the preview's sources.

All-or-nothing by design: no per-entry selection, and no disable-absent. The published catalogue is a curated SUBSET of what a plane may legitimately hold (vertex and vertexanthropic models are seeded but not published), so a one-click disable-absent would silently turn off models customers are routing to. The plan lists absent models read-only instead.

Request​

Responses​

Success