Automating updates with the write API

Push catalog updates straight from your ERP, PIM, or website — publish-scoped keys, batch imports, image batches, and the reports that come back.

Spreadsheets are the on-ramp; the publisher write API is how your systems keep TrueSpec current without a human in the loop. It's the same import engine as the portal upload — same validation, same in-place updates, same field-lock protections — driven by JSON over HTTPS.

The interactive API reference lives at truespec.net/docs; this page is the operational overview.

Keys: publish is a separate power

API keys are single-purpose: a key can read or publish, never both. An organization owner creates a publish-scoped key in the portal (Account → API keys). Publish keys can only ever write to your own organization's catalog — the key itself pins the tenant.

Treat a publish key like a production database credential: store it in your secret manager, rotate it if it ever leaks.

Batch imports

POST /v1/publish/imports accepts a batch of product rows using the same field vocabulary as the spreadsheet import (sku, name, brand, category, attribute columns…). The call returns immediately with a job id; poll GET /v1/publish/imports/{id} for status and the full report.

What to know before you wire it up:

• All-or-nothing per batch. If any row fails validation, the batch commits nothing and the report names every failing row and why. Fix and re-submit the whole batch — re-submission is safe because rows update in place by SKU.
• One import at a time per organization. Submit your next batch after the previous one finishes (large catalogs: send a few hundred rows per batch, serially).
• Start with a canary. Push one known row first and confirm it updated the product you expected rather than creating a new one — this catches SKU-format mismatches before they multiply.
• Missing required attributes normally fail the batch. Opt in with allow_missing_attributes: true and those rows are accepted as unpublished drafts instead; the report returns a worklist of exactly which attributes each product still needs. Drafts promote automatically when a later push fills the gaps. Invalid values still fail loudly — the flag relaxes "missing," never "wrong."
• The report is explicit. Created/updated counts, row-level errors, every field skipped because a hand edit locked it, and the missing-attribute worklist. Log it on your side.
• Removing an attribute is deliberate: include the attribute key in the row's remove_attributes (or remove_variant_attributes) list. Ordinary rows only add and update — they never delete what they don't mention.

Image batches

POST /v1/publish/images takes a batch of image URLs, each targeted at a SKU, with optional alt text, role, and sort order. TrueSpec fetches each URL, re-hosts the image on its CDN, and attaches it. Batches are additive and idempotent — re-sending the same URL for the same product doesn't duplicate it — and a pushed gallery image never displaces the primary image your team chose.

Two practical notes: the image URLs must be publicly reachable and serve the image bytes directly (no redirects), and jobs report per-image progress the same way imports do.

Sequencing a nightly sync

A robust publisher-side sync loop looks like:

1. Export changed products from your system of record.
2. Push in batches; poll each job to completion before the next.
3. Alert on any failed batch (the report tells you exactly which rows).
4. Review the skipped-fields list occasionally — it shows where your team's hand edits and your feed disagree, which is usually a signal to fix the data at the source.

For how API pushes interact with portal edits and spreadsheet uploads, see Updating your catalog.

Questions this guide didn't answer? Get in touch — or browse the interactive API reference.