API reference

Syncs

Pull sources re-sync automatically every six hours; use this API to sync on demand and to inspect run history.

List sync runs

GET/api/v1/syncs

The 50 most recent sync runs, newest first. Requires the read scope.

bash

curl https://useshelfready.com/api/v1/syncs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

Trigger a sync

POST/api/v1/syncs

Run a pull sync for one source (WooCommerce, BigCommerce, Magento, or feed URL) now. The call is synchronous and returns the run stats; a failed sync (unknown source, connector error) returns 422. Requires the write scope.

Parameter	Type	Description
`source_id`req	uuid	The source to sync. Find source IDs in Dashboard → Sources.

sync.sh

curl -X POST https://useshelfready.com/api/v1/syncs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809" }'

response.json

{
  "data": {
    "run_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "stats": { "seen": 1284, "upserted": 1284, "rejected": 0, "warnings": 37, "rejections": [] }
  }
}

Every successful sync re-renders your feeds, re-runs the audit, and emits a sync.completed webhook.

The run object

Parameter	Type	Description
`run_id`	uuid	Unique run identifier.
`source_id`	uuid \| null	The source this run belongs to.
`status`	string	running, succeeded, or failed.
`stats`	object	seen, upserted, rejected, warnings, and capped per-item rejections.
`started_at`	datetime	When the run started.
`finished_at`	datetime \| null	When the run finished, if it has.