API

Tool Agent API

Call Ecomwith tools from your agent, automation script, or internal workflow with an API key. This guide currently covers GTIN, QR Code, UTM Builder, and Break-even ROAS APIs.

Authentication
Create an API key from settings. The full secret is shown once, so copy it into your agent or secret manager. Later views only show a masked key.
Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...
Quota And Rate Limits
API usage is tracked separately. Successful and limit responses expose quota.remaining and rateLimit.remaining (plus the matching X-* headers). Minute limits use a UTC minute window and are counted per API key and tool; requests beyond the limit return 429 rate_limited, so wait for Retry-After before retrying.
X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30
Safe Retries
When a request times out or your agent retries automatically, reuse the same Idempotency-Key. The same key and body reuse the result; a different body returns idempotency_conflict, while an active request returns idempotency_in_progress.
Idempotency-Key: order-sync-2026-06-14-001
Grant the smallest scope
Choose only the tool scope each API key needs, such as tools:gtin:generate. A scope limits tools; it does not increase the owner membership tier, quota, or rate limit.
Scope: tools:gtin:generate
Keep the API key secret
The full API key is shown only once. Store it in an environment variable or secret manager; never put it in code, URLs, logs, screenshots, or chat. Delete and recreate it if you suspect exposure.
ECOMWITH_API_KEY=ecw_live_...

Errors And Recovery

Error responses use error.code and error.message. Handle the status and code first, then decide whether to wait or retry the same business request with its original Idempotency-Key.

400invalid_request

Fix the JSON body before sending again; do not repeat an unchanged request.

401authentication_required / invalid_api_key

Check Authorization: Bearer or X-API-Key; never put the full key in error logs.

403membership_required / insufficient_scope

Check the current plan and the key scope; a scope cannot increase membership quota.

409idempotency_conflict / idempotency_in_progress

Keep one key for the same business request; stop on conflict, or wait and retry an active request with the same key.

413payload_too_large

Reduce the request body to the current plan payload limit before sending again.

429quota_exceeded / rate_limited / concurrency_limited

Read X-Quota-*, X-RateLimit-*, and Retry-After; stop at zero quota and wait for rate or concurrency limits.

Error response shape

{"object":"tool_api.error","error":{"code":"invalid_request","message":"Request body must be a JSON object."}}

Endpoints

GTIN API
Generate GTIN-14 values with valid check digits in batches for development and feed QA. They are not GS1-assigned product identifiers. Quota is counted by generated values.
POST /api/v1/tools/gtin/generate
QR Code API
Generate SVG or PNG data URL QR codes from links or text. Quota is counted by request.
POST /api/v1/tools/qrcode/generate
UTM Builder API
Apply one UTM parameter set to one or many landing page URLs. Optional id and sourcePlatform values are emitted as utm_id and utm_source_platform. Quota is counted by successfully built links.
POST /api/v1/tools/utm-builder/build
Break-even ROAS API
Calculate break-even ROAS, target-profit ROAS, and CPA guardrails from price, costs, fees, and refund reserve.
POST /api/v1/tools/break-even-roas/calculate
OpenAPI JSON
/openapi.json
/openapi.json