Back to UTM Builder toolAPI

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.

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."}}

Current Plan Limits

Limits are calculated from the current membership tier of the API key owner. Minute limits are counted separately for each API key and tool; requests beyond the limit return 429 rate_limited. Send requests sequentially and treat quota and rateLimit in each response as the source of truth.

Basic

Not included in API access today
Daily quota
Unavailable
Per request
Unavailable
Per minute
Unavailable
How to use it
If the API returns membership_required, stop and check the account plan.

Pro

Included
Daily quota
1,000 links
Per request
Up to 100 links
Per minute
60 requests
How to use it
urls is the batch link list. Building 10 successful links consumes 10 link units. Stop or split the request when quota.remaining is lower than the link count.

Max

Included
Daily quota
10,000 links
Per request
Up to 500 links
Per minute
200 requests
How to use it
urls is the batch link list. Building 10 successful links consumes 10 link units. Stop or split the request when quota.remaining is lower than the link count.

Send Requests Sequentially

For the same API key and tool, Ecomwith handles one request at a time. If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.

Copy This To Your Agent
Give this instruction to your automation agent so it knows how to authenticate, request, handle quota, rate limits, and safe retries.
You are my automation agent. Use the Ecomwith Tool API to call the UTM Builder API, and never print the full API key.

Authentication:
- Read ECOMWITH_API_KEY from the environment.
- Send Authorization: Bearer <ECOMWITH_API_KEY>.

Request:
- Endpoint: POST https://ecomwith.com/api/v1/tools/utm-builder/build
- Body example: {"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience","id":"campaign-42","sourcePlatform":"meta_ads"}
- Building 10 successful links consumes 10 link units. URLs returned in invalid do not consume quota.

Current limits:
- Pro: 1,000 links per day, up to 100 links per request, up to 60 requests per minute.
- Max: 10,000 links per day, up to 500 links per request, up to 200 requests per minute.

Rules:
- Send requests sequentially. Do not call the same tool concurrently.
- Use one stable Idempotency-Key per business batch, for example utm-campaign-2026-06-17-batch-1.
- Handle concurrency_limited, rate_limited, quota_exceeded, and idempotency_conflict by stopping or retrying according to the code.

On success, return links, invalid, quota.remaining, and rateLimit.remaining.

Example Requests

curl -X POST https://ecomwith.com/api/v1/tools/utm-builder/build \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: utm-batch-001" \
  -d '{"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience","id":"campaign-42","sourcePlatform":"meta_ads"}'