API Documentation

Authentication

Create a scoped token in your account, then send it with every request.

Authorization: Bearer YOUR_TOKEN

Endpoints

GET /api/v1/links?page=1&per_page=25 POST /api/v1/links PATCH /api/v1/links/{id} DELETE /api/v1/links/{id} GET /api/v1/links/{id}/analytics?period=30 POST /api/v1/conversions

Create a link

curl -X POST https://4ul.ink/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-launch-2026-01" \
  -d '{"destination_url":"https://example.com","slug":"example"}'

Update a link

curl -X PATCH https://4ul.ink/api/v1/links/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com/new","title":"Launch","is_active":true}'

Token scopes

links:read lists links. links:write creates, updates, disables links and records conversions. analytics:read reads link analytics.

Pagination and limits

List responses include page, per_page, total and total_pages. per_page accepts 1-100. Token requests are rate-limited and monthly plan usage can return HTTP 429 with Retry-After and RateLimit headers. Redirects keep working when an API or analytics limit is reached.

Idempotency

Send an Idempotency-Key with link-creation requests that may be retried. Keys are scoped to the workspace and kept for 24 hours. An identical retry returns the stored response with Idempotent-Replayed: true; reusing a key with different input returns HTTP 409.

Errors

{
  "error": "destination_url must be a valid public HTTP or HTTPS URL.",
  "code": "invalid_destination"
}

Common statuses: 400 invalid JSON, 401 invalid token, 403 missing scope or entitlement, 404 object not found in this workspace, 409 conflict, 415 wrong content type, 422 validation error, and 429 rate or usage limit. Object access is always restricted to the token workspace.

Webhook firmati

Available events are link.clicked and conversion.created. Deliveries include X-4ulink-Event, X-4ulink-Delivery, X-4ulink-Timestamp and X-4ulink-Signature. Verify the HMAC signature over “timestamp.payload”, reject old timestamps, and store the delivery ID to prevent replay. Failed deliveries use a bounded retry queue.

Machine-readable contract

OpenAPI 3.1 YAML · Current API version: v1. Breaking changes require a new versioned base path.

API access and signed webhooks are available on supported paid plans.

Avvia la prova Pro di 14 giorni