Quickstart

Get up and running with the utm.bar Open API in under 5 minutes.

Step 1 — Create an API Key

1. Log in to your Dashboard and navigate to Developer in the left sidebar
2. Click Create API Key
3. Give the key a name (e.g. CI Bot or Marketing Automation)
4. Select the permission scopes you need:
   • links:read — list and view links, fetch statistics
   • links:write — create and update links
   • links:delete — disable and delete links
5. Click Create

Important: The full API key is shown only once at creation. Copy it immediately and store it securely. Do not commit it to source code or share it publicly.

Your key looks like this:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2 — Make Your First Request

Create a Short Link

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/blog/launch-2026",
    "title": "Product Launch Post",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch-2026"
  }'

Response:

{
  "data": {
    "id": "01960000-0000-0000-0000-000000000000",
    "code": "xK3mP9",
    "short_url": "https://utm.bar/xK3mP9",
    "original_url": "https://example.com/blog/launch-2026",
    "title": "Product Launch Post",
    "is_active": true,
    "click_count": 0,
    "expires_at": null,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch-2026",
    "created_at": "2026-05-25T00:00:00Z"
  }
}

List Your Links

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

Step 3 — Authenticate Correctly

Use one of these two methods in every request:

Authorization: Bearer sk_live_xxxx

X-API-Key: sk_live_xxxx

If the key is missing or invalid, you receive 401 Unauthorized.
If the key lacks the required scope for an endpoint, you receive 403 Forbidden.

Step 4 — Handle Errors

The API always returns a consistent error body:

{
  "error": "invalid_request",
  "message": "original_url is required",
  "request_id": "req_abc123"
}

Common status codes:

Next Steps

• Read the full API Reference for all endpoints
• Set up rate limit headers monitoring (X-RateLimit-Remaining)
• Use custom_code for branded short links in your campaigns