inPIPE UTM API — Documentation #

Connect an AI assistant or automation to your inPIPE UTM Generator over a secure, key-gated REST API. Create, read, update, and delete UTM-tagged links programmatically — the same links you’d build in the UTM Generator, now available to your tools.

Plugin: inPIPE by Seresa (Free) · Requires: UTM Processing enabled.

Overview #

Stop guessing where your traffic comes from #

Every click to your site has a story — which ad, which email, which post sent it. Without tracking, that story is lost: your analytics dumps it all into a vague “Direct / unknown” pile, and you’re left guessing what’s actually driving results.

UTM links fix that. A UTM link is a normal URL with a few tracking tags on the end:

https://your-site.com/blog?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale

Those tags tell Google Analytics (and every other tool) exactly where each visitor came from — so you can see what’s working and double down on it.

inPIPE makes the links. The API makes them effortless. #

The UTM Generator builds, saves, and shortens these links for you, keeping your campaign naming consistent every time (no more Summer_Sale in one link and summer-sale in the next). Each link is saved two ways: a short coded link to share (?u4gf2=…) and the full tagged URL behind it.

The UTM API takes it one step further — it hands that whole Generator to your AI assistant and automation tools, so the busywork does itself:

• ⚡ Build a whole campaign in seconds — generate dozens of consistent links from a single prompt, instead of one-by-one by hand.
• 🎯 Never break your naming again — the same rules and cleanup run on every link, automatically.
• 🔁 Reuse, don’t duplicate — your assistant looks up existing links before making new ones.
• 🤖 Work where you already are — create, edit, and remove links straight from your AI chat, no WordPress login needed.

New here? The quickest start is the Connect an AI Assistant to Your UTM Links guide — download a ready-made skill file, paste in your key, and just ask in plain language.

1. Before you start #

The UTM API only works when two conditions are met:

1. UTM Processing is ON (Settings → UTM Processing Settings). This is the master switch for all UTM features. If it’s off, every API call returns 423 Admin: Locked.
2. Your site is served over HTTPS. The API refuses plain http:// requests (your key would travel in clear text). If your site sits behind an SSL-terminating proxy (e.g. Cloudflare), an admin can enable proxy trust — contact support if you need this.

2. Enabling the API #

In Settings → UTM Processing Settings, with UTM Processing on, you’ll see the UTM API Access panel:

1. Turn on Enable UTM API Access (the master switch). Your two API keys are generated automatically the first time.
2. Turn on the key you need — each toggle enables one key, independently:
   • Read API — enables the Read API key (list links, read status).
   • Update API — enables the Update API key (list, read status, create, edit, and delete). (Delete is part of Update — there’s no separate delete switch.)

The two toggles don’t affect each other. The Update API key works whenever Update API is on — for reads and writes — whether or not Read API is on. The Read API key works whenever Read API is on. (Turning a key’s toggle off locks that key completely, including its reads.)

Tip: For anything that only needs to look (reports, audits), use the Read API key and keep Update API off — a leaked Read API key can never change anything. Turn Update API on only for tools that must create or change links.

3. API Keys #

You get two keys, each with a different scope:

The Read API key has ro in it; the Update API key has rw — and the panel labels each one, so you always know which is which.

• Least privilege: give the Read API key to anything that only needs to look (reports, audits). Give the Update API key only to tools that must create or change links.
• Copy anytime: the panel shows each key masked (••••••••a787). Click the copy icon to copy the full key whenever you need it. Regenerate (the refresh icon) replaces the key and turns off the old one.
• Regenerate turns off the old key immediately. Update any tool or automation using it afterward.
• Rotate regularly: for better security, regenerate your keys every few months — and right away if a key may have leaked.
• Each key is unique to your site. A leaked key only affects this one site, and its damage is bounded by the rate limits and the 10,000-record storage cap.

Auth header: every request must send the key in the header X-InPipe-Key: <your key>.

4. Endpoints #

Base URL: https://YOUR-SITE.com/wp-json/inpipe/v1/ext

The Scope column is the key that’s allowed: read endpoints (RO) accept either key; write endpoints (RW) require the Update API key. For a call to succeed, the toggle for the key you send must also be on — Read API for the Read API key, Update API for the Update API key. (The Update API key covers the read endpoints too, as long as Update API is on.)

All responses are JSON with the same envelope:

{ "success": true,  "data": { ... }, "error": null }
{ "success": false, "data": null,    "error": { "code": "...", "message": "..." } }

4.1 Status — GET /status #

curl https://YOUR-SITE.com/wp-json/inpipe/v1/ext/status 
  -H "X-InPipe-Key: YOUR-READ-API-KEY"

{ "success": true, "error": null, "data": {
  "read_enabled": true, "write_enabled": true,
  "limits": {
    "read":   { "per_second": 3, "per_minute": 60, "per_hour": 2500, "per_hour_remaining": 2487 },
    "write":  { "per_second": 1, "per_minute": 30, "per_hour": 1200, "per_hour_remaining": 1191 },
    "delete": { "per_second": 1, "per_minute": 10, "per_hour": 400,  "per_hour_remaining": 400  } },
  "storage_used": 42, "storage_cap": 10000, "storage_remaining": 9958 } }

4.2 Create — POST /utm-generate (omit code) #

curl -X POST https://YOUR-SITE.com/wp-json/inpipe/v1/ext/utm-generate 
  -H "X-InPipe-Key: YOUR-UPDATE-API-KEY" -H "Content-Type: application/json" 
  -d '{
    "base_url": "https://YOUR-SITE.com/blog",
    "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "summer_sale",
    "custom_params": [ { "key": "partner", "value": "acme" } ]
  }'

{ "success": true, "error": null, "data": {
  "code": "u4gf2",
  "coded_url": "https://YOUR-SITE.com/blog?u4gf2=84729301",
  "full_url": "https://YOUR-SITE.com/blog?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale&partner=acme",
  "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "summer_sale",
  "utm_term": "", "utm_content": "", "utm_id": "",
  "custom_params": [ { "key": "partner", "value": "acme" } ],
  "created_at": "2026-06-17T14:00:00Z", "updated_at": "2026-06-17T14:00:00Z" } }

The code (e.g. u4gf2) is the link’s identifier — use it to update or delete later.

Which URL do I share? Each link comes back with two:

Both point to the same destination with the same tracking. Use coded_url when you want a tidy link; use full_url when you (or another tool) need the UTM parameters spelled out.

4.3 Update — POST /utm-generate (include code) #

Send the code plus only the fields you want to change. Omitted fields keep their existing values — they are not wiped.

curl -X POST https://YOUR-SITE.com/wp-json/inpipe/v1/ext/utm-generate 
  -H "X-InPipe-Key: YOUR-UPDATE-API-KEY" -H "Content-Type: application/json" 
  -d '{ "code": "u4gf2", "utm_source": "bing" }'

4.4 List — GET /utm-list #

GET /utm-list?page=1&per_page=10&source=google&medium=cpc&campaign=summer_sale
              &search=keyword&date_from=2026-01-01&date_to=2026-06-01

{ "success": true, "error": null, "data": {
  "records": [ { "code": "u4gf2", "full_url": "...", "...": "..." } ],
  "total": 42, "page": 1, "per_page": 10 } }

4.5 Delete — DELETE /utm-delete #

Deletes permanently (there is no trash/recovery). Delete one link per call, by code.

curl -X DELETE https://YOUR-SITE.com/wp-json/inpipe/v1/ext/utm-delete 
  -H "X-InPipe-Key: YOUR-UPDATE-API-KEY" -H "Content-Type: application/json" 
  -d '{ "code": "u4gf2" }'

{ "success": true, "error": null, "data": { "code": "u4gf2", "deleted": true } }

5. Fields & rules #

Value cleaning: spaces become +, apostrophes are removed. If a value contains characters that aren’t allowed (e.g. <, >, ", ;), the request is rejected with 400 rather than silently altered — so what you send is exactly what’s stored.

6. Limits #

Sensible, shared-hosting-safe limits are applied automatically (no configuration needed). Each request must pass all three windows:

• Storage cap: 10,000 active links. New creates are blocked at the cap (507); you can still read, update, and delete to clean down. (Updates and deletes are never cap-blocked.)
• Over any limit returns 429 with a Retry-After header telling you how many seconds to wait. The status endpoint reports each operation’s remaining hourly budget (per_hour_remaining) so a tool can pace itself.

7. Response codes #

All error responses are intentionally terse — they carry a short code and a generic message, and never reveal which internal setting or state produced them.

8. Troubleshooting #

• Everything returns 401 → You’re calling over http://, or the key is wrong/missing. Use https:// and check the X-InPipe-Key header.
• Everything returns 423 → UTM Processing is off, the master UTM API Access is off, or the toggle for the key you’re sending is off (Read API for the Read API key, Update API for the Update API key). Check Settings.
• Writes return 403 → You’re using the Read API key for a write or delete. Use the Update API key.
• Create returns 400 “off-domain” → base_url must point at your own site’s domain.
• Create returns 507 → You’ve hit the 10,000-link cap. Delete unused links and retry.
• The panel doesn’t appear → UTM Processing must be ON for the UTM API Access panel to show.

9. Security notes #

• Keys are bearer tokens — treat them like passwords. Don’t commit them to public repos.
• Keys are encrypted at rest. Each key is stored encrypted in the database (libsodium, with a key that lives in wp-config, not the database). A database or backup leak alone cannot expose your keys. You can copy a key from the panel at any time; Regenerate replaces it with a new one and invalidates the old.
• The API is HTTPS-only and server-to-server (no browser/CORS access).
• Errors reveal nothing about your setup. Anyone without a valid key only ever sees a generic 401 — they can’t tell whether the API is on, which toggles are set, or even that the endpoint exists. Distinct codes (403/423/429/etc.) appear only after a valid key is proven, so the surface can’t be probed for internal state.
• Disabling UTM Processing (or the API toggles) instantly locks every endpoint; your keys and settings are preserved and restored when you re-enable.
• Need to revoke access right now? Regenerate the key (kills the old one instantly) or turn off the relevant toggle.

For help, contact support with your site URL and the exact response code you’re seeing (never share the full key).