API Reference

Base URL: https://open.utm.bar/v1
Authentication: Authorization: Bearer sk_live_xxxx or X-API-Key: sk_live_xxxx

Short Links

Create a Short Link

POST /v1/links

Scopes required: links:write

Request Body

curl -X POST https://open.utm.bar/v1/links \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/page",
    "title": "My Link",
    "custom_code": "launch-2026",
    "utm_source": "twitter",
    "utm_medium": "social"
  }'

Response 201 Created

{
  "data": {
    "id": "...",
    "code": "launch-2026",
    "short_url": "https://utm.bar/launch-2026",
    "original_url": "https://example.com/page",
    "title": "My Link",
    "is_active": true,
    "click_count": 0,
    "external_id": "order_98765",
    "expires_at": null,
    "utm_source": "twitter",
    "utm_medium": "social",
    "created_at": "2026-05-25T00:00:00Z"
  }
}

custom_code conflicts return 409 Conflict.

List Short Links

GET /v1/links

Scopes required: links:read

Query Parameters

curl "https://open.utm.bar/v1/links?page=1&page_size=20" \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK

{
  "data": {
    "items": [ /* array of link objects */ ],
    "total": 42,
    "page": 1,
    "page_size": 20
  }
}

Get a Single Link

GET /v1/links/:code

Scopes required: links:read

curl https://open.utm.bar/v1/links/launch-2026 \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK — returns a single link object.

Get a Link by External ID

GET /v1/links/external/:external_id

Scopes required: links:read

Look up a short link by the external_id you provided at creation time. Returns 404 if no match is found.

curl https://open.utm.bar/v1/links/external/order_98765 \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK

{
  "data": {
    "id": "...",
    "code": "launch-2026",
    "short_url": "https://utm.bar/launch-2026",
    "original_url": "https://example.com/page",
    "external_id": "order_98765",
    "is_active": true,
    "click_count": 42,
    "created_at": "2026-05-25T00:00:00Z"
  }
}

Update a Link

PATCH /v1/links/:code

Scopes required: links:write

original_url and code cannot be changed after creation.

Request Body (all fields optional)

curl -X PATCH https://open.utm.bar/v1/links/launch-2026 \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title", "expires_at": "2026-12-31T23:59:59Z" }'

Response 200 OK — returns the updated link object.

Disable a Link

POST /v1/links/:code/disable

Scopes required: links:delete

curl -X POST https://open.utm.bar/v1/links/launch-2026/disable \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK

Enable a Link

POST /v1/links/:code/enable

Scopes required: links:write

curl -X POST https://open.utm.bar/v1/links/launch-2026/enable \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK

Delete a Link

DELETE /v1/links/:code

Scopes required: links:delete

Deletion is permanent. Consider disabling instead if you may need the link later.

curl -X DELETE https://open.utm.bar/v1/links/launch-2026 \
  -H "Authorization: Bearer sk_live_xxxx"

Response 204 No Content

Get Link Statistics

GET /v1/links/:code/stats

Scopes required: links:read

Query Parameters

curl "https://open.utm.bar/v1/links/launch-2026/stats?start=2026-05-01&end=2026-05-25&tz=Asia/Shanghai" \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK

{
  "data": {
    "total_clicks": 1024,
    "unique_clicks": 876,
    "tz": "Asia/Shanghai",
    "daily": [
      { "date": "2026-05-01", "clicks": 40, "unique_clicks": 35 },
      { "date": "2026-05-02", "clicks": 55, "unique_clicks": 48 }
    ]
  }
}

Rate Limits

Limits apply per team across all API keys.

When a limit is exceeded, the API returns 429 Too Many Requests with these headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1748140860
Retry-After: 30

Permission Scopes

Error Responses

All errors use the same structure:

{
  "error": "error_code",
  "message": "Human-readable description",
  "request_id": "req_abc123"
}