WURL developer API

The API requires a current paid Pro subscription and a bearer token from Developer API. Free plans, trials and complimentary Pro grants are ineligible. Tokens stop authorizing requests when payment eligibility, membership or account access ends.

Download the OpenAPI specification

Authentication and limits

Use HTTPS and the Authorization: Bearer header. Cookies are never an API authentication fallback. Reads allow 600 requests per workspace per minute; mutations allow 60. Limits use fixed 60-second windows. A 429 response includes Retry-After. Link capacity and account creation limits also apply. Tokens have links:read, links:write and analytics:read scopes.

Create a link

curl https://www.wurl.us/api/v1/links \
  -H "Authorization: Bearer $WURL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-link" \
  -d '{"url":"https://example.com","title":"Example"}'

Request bodies are limited to 64 KiB. Creation returns 201 and an opaque ID. Reuse the same key and JSON body to retry safely. A changed body with the same key returns 409. Keys are retained for the workspace lifetime; a deleted result returns 410.

Endpoints

• GET /api/v1/links?limit=50&after=… — list up to 100 links per page, with next_cursor.
• POST /api/v1/links — create with an Idempotency-Key.
• GET, PATCH, DELETE /api/v1/links/{id} — inspect, update or permanently delete.
• POST /api/v1/links/{id}/simulate — evaluate country, region, device, os, now and query without recording a visit.
• GET /api/v1/analytics?days=30 — daily aggregate reporting.

Updates accept title, url, is_active, settings, and an optional version for optimistic concurrency. Omitting a setting preserves it. Schedules use UTC timestamps. Rules use ascending priority, then array order; conditions within a rule are ANDed. Daily visitor totals are not monthly distinct people.

Webhooks

Subscribe to link.created, link.updated, link.deleted, link.unhealthy and link.recovered. Payloads contain an event ID, opaque link ID, type and UTC occurrence time. They omit destination URLs. Delivery is at least once: deduplicate using the event ID.

Verify WURL-Signature, formatted t=TIMESTAMP,v1=HEX_HMAC. Compute HMAC-SHA256 over TIMESTAMP + "." + the exact raw request body using your signing secret, compare in constant time, and reject timestamps more than five minutes old. Secret rotation immediately affects subsequent attempts. Endpoints must use public HTTPS; redirects are not followed.

Return 2xx to acknowledge. Failed delivery retries up to eight attempts with exponential backoff and jitter, capped at six hours between attempts. Inspect failures in Webhooks. No event is sent for each click. Health alerts require repeated failures; 401, 403 and 429 results remain uncertain.