Store

Push a catalog

Up to 500 rows, each carrying the store's one country. Needs an API key: the intake names the merchant by the key, so an OAuth token receives 403 key_required. 202 with the push id when rows were queued, or when nothing was queued and the push record exists; 200 with a null push_id and a reason when nothing was queued and nothing was recorded. Rows inside the allowance are analysed and the rest are deferred and reported on the push record — a push is never refused for size. An unchanged row takes the content-hash exit and costs nothing; force re-analyses every row.

post/v1/catalog

Request

  • Base URL: https://carbonguru.io
  • URL: https://carbonguru.io/v1/catalog
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A key of the caller's choosing, held 24 hours and scoped to the account, the method and the path. The same key with the same body replays the stored response with Idempotent-Replayed: true. The same key with a different body is a 409 idempotency_key_reuse. A request still running under the key is a 409 idempotency_in_progress. A key longer than 255 characters or holding control characters is a 422. A write whose record cannot be stored is still processed once, without the replay guarantee. A response carrying a secret is never replayed: the second request receives a 409 idempotency_secret_not_replayable.

Request body

forceboolean

Re-analyse every row, unchanged content included. Each re-analysis is billable.

Response

Nothing was queued and no push record was written. reason names why and push_id is null.

push_idstring nullable required

The push's id, which reads back at GET /v1/pushes/{push_id}.

skippedobject[] required

Up to 50 refused rows, each with its position and stated reason. The full list is on the push record.

allowance_remaininginteger nullable

Analyses left in the period. Null means unlimited.

reasonstring nullable

Present on the 200: the intake's own word for why nothing was queued, such as not_entitled or allowance_reached.

Changes

No recorded changes to this operation across all 1 revision of this API.