api-reference

API Reference

Session-authenticated HTTP APIs for import, destinations, publish, plus v1 aliases.

Base URL and auth

Development: http://127.0.0.1:3000. Send the session cookie from /api/auth/session for dashboard-equivalent routes. The extension ingest route uses x-toksync-api-key instead.

All mutating routes expect Content-Type: application/json unless you are uploading a document (multipart).

Import URL

Persist scraped products into the catalog:

bash

curl -X POST http://127.0.0.1:3000/api/import/url \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://store.example/p/1"],"persist":true}'

await fetch('/api/v1/import/url', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ urls: [url], persist: true }),
});

Set persist: false (or omit per handler defaults) for preview-only. Private URLs are rejected unless local ingest is enabled.

Publish

bash

curl -X POST http://127.0.0.1:3000/api/products/publish \
  -H "Content-Type: application/json" \
  -d '{"productIds":["…"],"destinationAccountIds":["…"]}'

Both arrays must be non-empty. Jobs enqueue per destination bulkhead. Poll product detail or sync logs for completion; this call returning 200 means **accepted**, not “Amazon listed.”

Destinations

bash

curl http://127.0.0.1:3000/api/destinations

Delete with DELETE /api/destinations?id=<destinationAccountId>. OAuth connect URLs are channel-specific (see TikTok, Shopify pages).

v1 aliases

/api/v1/* maps to the same handlers for production gateways. Prefer one prefix in your scripts and stick to it.

Error shape

Expect JSON { "error": "…" } with 4xx/5xx. 401 = missing session or key. 422 = validation (empty urls, unknown product id). 429 = you hit **our** limiter or we are passing through a channel wait — read the message.

Interactive route list: **Endpoints Specification**.