Client Links API
Manage short links, read click analytics, subscribe to uptime webhooks, and monitor destination availability with the client-scoped Links API.
Overview
The Client Links API lets an agency (or an individual client) create and manage short links, read per-link click analytics, subscribe to uptime webhooks, and monitor destination availability. It is scoped to a single client (location) per request and authenticated with a client key — not an admin session. See Authentication for the key types.
Base URL
All endpoints are mounted under the /client/v1 prefix.
https://mythic-analytics.gulp.workers.dev/client/v1
Response envelope
Successful responses use a JSON envelope.
Always true on success.
Resource payload. Shape depends on the endpoint. List endpoints return an array.
Number of items returned. Present on list endpoints (/links, /links/webhooks).
Present on delete responses (true).
The analytics, trend, stream, UTM-values, CWV, and uptime endpoints are
proxies to Tinybird and return Tinybird's raw JSON envelope
(meta / data / rows / statistics) rather than the success envelope.
Key concepts
| Concept | Description |
|---|---|
| Short Link | A slug on a client's domain that redirects to a destination URL and tracks clicks. Stored in link_redirects. |
| Analytics | Per-link click data (analytics, trend, stream, UTM values) served from Tinybird. |
| Uptime Webhook | An HTTP callback fired on link_down / link_up events. Backed by tenant_actions. |
| Uptime Monitoring | Automatic HEAD checks (~every 5 minutes) of enabled link destinations; read via the uptime endpoints. |
Read vs. write access
Read endpoints accept either key type. Write endpoints (create/update/delete links, status changes, and webhook mutations) require an agency key (ak_). A location secret key (sk_) is read-only; write attempts return 403.
Error handling
Errors return a bare error string (not the success envelope):
{ "error": "Write access requires an agency key (ak_)" }
| Status | Meaning |
|---|---|
400 | Invalid JSON body or validation error |
401 | Missing/invalid key, or missing location_id for an agency key |
403 | Write attempted with a read-only secret key (sk_) |
404 | Link or webhook not found for this location |
409 | Duplicate slug for this client |
503 | Analytics backend not configured |
Check both the HTTP status code and the error field for programmatic error handling.