API reference

Send your catalogue to omniSKU, have it checked and fixed for each channel, and pull the clean feeds back. JSON over HTTPS, versioned under /api/v1.

Getting started

Create a token under Settings → API access, then send a catalogue and ask for a channel to be checked. Scanning costs 1 credit per new SKU, exactly as in the app; re-checking the same SKUs is included. AI fixes are subject to fair use: they are capped in proportion to what the account has paid, and message says when they were paused.

# 1. Create a catalogue and scan it for Google Shopping
curl -X POST https://omnisku.com/api/v1/catalogs \
  -H "Authorization: Bearer $OMNISKU_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Spring range", "channels": ["google_shopping"],
       "products": [{"sku": "TEE-1", "title": "Classic Cotton Tee", "price": "19.50"}]}'
# → 202 Accepted, status "scanning"

# 2. Poll (or use a webhook) until status is "ready"
curl -H "Authorization: Bearer $OMNISKU_TOKEN" https://omnisku.com/api/v1/catalogs/42

# 3. Download the cleaned feed
curl -H "Authorization: Bearer $OMNISKU_TOKEN" \
  "https://omnisku.com/api/v1/catalogs/42/channels/google_shopping/feed?format=xml"

Authentication

Send your token in an Authorization: Bearer osk_… header on every request. Tokens are shown once when created and stored only as a hash, so keep them in a secret manager. A token is either read-only or read + write; revoke one at any time in Settings.

Tokens act as you: they only ever see your own catalogues.

Formats

Accepted on the way in

• JSON: a products array of objects. Nested objects flatten to shipping_price-style keys; arrays are comma-joined.
• File upload (multipart, field file): CSV, TSV, XML or JSON.
• XML: Google Shopping RSS 2.0 (g: namespace), Atom, or any XML with a repeating product element. Namespace prefixes are dropped (<g:id> becomes id), nested elements flatten (shipping_price), repeated elements are comma-joined, and attributes become columns. DOCTYPE and entity declarations are rejected.

Columns are matched to omniSKU's product fields automatically (id, g:image_link, Variant SKU…). Pass a mapping to override, for example {"Product Code": "sku"}. Every catalogue needs a SKU column. Canonical fields: sku, group_id, title, description, brand, price, sale_price, currency, quantity, availability, condition, link, image_link, additional_images, gtin, mpn, category, color, size, material, gender, age_group, tags, bullet_points.

Available on the way out

Catalogues

Products & sync

Issues & fixes

Feeds

XML feeds are RSS 2.0 with the g: namespace, the shape Google Merchant Center and Meta Commerce Manager read.

Hosted feed URLs

For a channel that fetches a feed on a schedule, use the hosted URL from the catalogue response (or from the channel page in the app): /feeds/<token>/google_shopping.xml. It needs no header, so keep it private; regenerate it from the app to revoke the old one. It always serves the latest fixed data.

omniSKU doesn't push to Google, Meta, Amazon or Etsy for you yet. You pull the feed, or point the channel at the hosted URL.

Webhooks

Add endpoints in Settings or with the API. Each delivery is a POST with a JSON body {id, event, created_at, data}, retried with back-off on failure, and an endpoint that keeps failing is paused. Webhook URLs must be public https addresses.

Verifying a delivery

Each request carries X-OmniSKU-Timestamp and X-OmniSKU-Signature. The signature is sha256= plus the hex HMAC-SHA256 of "{timestamp}.{raw body}" using your secret. Compare in constant time and reject old timestamps.

expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
ok = ActiveSupport::SecurityUtils.secure_compare(expected, signature_header) &&
     (Time.now.to_i - timestamp.to_i).abs < 300

MCP server

omniSKU is also a remote Model Context Protocol server, so an AI assistant can do the work for you: upload a catalogue, check it, fix it and hand back the feed. It speaks Streamable HTTP at:

https://omnisku.com/mcp

Add it as a custom connector (or remote MCP server) in an assistant that supports them, and approve access when asked. There is nothing to install and no token to copy. In Claude Code:

claude mcp add --transport http omnisku https://omnisku.com/mcp

Clients that can't do OAuth can send a Settings token instead: Authorization: Bearer osk_….

There is also an optimise_catalog prompt that walks through the whole flow. Choosing Read only on the approval screen hides every write tool. Results are summarised and truncated so large catalogues don't overwhelm the assistant, and product text is marked as data, not instructions. The server has no delete tool.

OAuth

The MCP server uses OAuth 2.1 with PKCE (S256, required) and public clients. Compliant clients discover everything themselves:

Access tokens issued this way also work on the REST API above.

Errors & limits

Errors are JSON: {"error": {"code": "…", "message": "…"}}.

Catalogues are capped at 50,000 rows and uploads at 100 MB.