REST API v1

API documentation

Programmatic access to links and analytics. Available on Pro and Team plans.

Getting started

Base URL: https://getowl.ai/api/v1

All requests require an API key in the Authorization header. Create keys in Settings → API keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://getowl.ai/api/v1/links"

Authentication

Send your secret key as a Bearer token on every request:

Authorization: Bearer sk_live_...

Keys are scoped to a workspace. Responses only include data for that workspace.

Links

GET/api/v1/links

List links in the authenticated workspace. Results are paginated and sorted by creation date (newest first).

Query parameters

page — zero-based page index (default 0)
take — page size, 1–50 (default 20)

Example response

{
  "items": [
    {
      "id": "uuid",
      "shortCode": "abc123",
      "ddbPartitionKey": "abc123",
      "destinationUrl": "https://example.com",
      "title": null,
      "tags": [],
      "createdAt": "2026-06-06T06:00:00.000Z"
    }
  ],
  "page": 0,
  "take": 20
}

Link analytics

GET/api/v1/links/{identifier}/analytics

Full analytics for a single link — summary, timeseries, and breakdowns. Identify the link by UUID (from GET /links), exact ddbPartitionKey (URL-encoded), or shortCode when unique in the workspace.

Query parameters

from — ISO datetime start of window (optional)
to — ISO datetime end of window (optional)
granularity — hour or day (default day)

Example response

{
  "link": { "id": "...", "shortCode": "abc123", "destinationUrl": "..." },
  "summary": { "clicks": 1284, "uniqueVisitors": 902 },
  "timeseries": { "points": [{ "time": "2026-06-01", "clicks": 42 }] },
  "breakdowns": {
    "countries": [{ "country": "IN", "clicks": 512 }],
    "devices": [{ "name": "mobile", "clicks": 780 }],
    "browsers": [],
    "os": [],
    "referrers": [],
    "ruleVariants": [],
    "geoRuleHits": []
  }
}

Workspace analytics

Fetch individual metrics via GET /api/v1/analytics/{metric}. Optional filters: shortCode, from, to. Use granularity on timeseries.

/analytics/timeseries

/analytics/countries

/analytics/devices

/analytics/browsers

/analytics/os

/analytics/referrers

/analytics/unique-visitors

/analytics/top-links

/analytics/rule-variants

/analytics/geo-rule-hits

/analytics/link-click-totals

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://getowl.ai/api/v1/analytics/countries?from=2026-06-01&to=2026-06-06"

Errors & limits

Code	Meaning
401	Missing or invalid API key
404	Resource not found or unknown analytics metric
429	Rate limit exceeded for the workspace
500	Server error — retry with backoff

Rate limits apply per workspace. Contact hello@getowl.ai for higher throughput on Team plans.