API guide
Create short links, change destinations and read click stats from your own apps, spreadsheets or automations. JSON over HTTPS.
1. Get a key
In the dashboard open Settings → API and create a key. It's shown once, so copy it somewhere safe. Send it on every request:
Authorization: Bearer gk_live_…
Base address: https://gotly.link/api/v1
2. Create a link
curl -X POST https://gotly.link/api/v1/links \
-H "Authorization: Bearer $GOTLY_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webinar", "slug": "webinar", "title": "Webinar", "tags": ["launch"]}'
{
"id": 42, "slug": "webinar", "short": "https://gotly.link/webinar",
"url": "https://example.com/webinar", "title": "Webinar", "tags": ["launch"],
"status": "active", "clicks": 0, "domain": "gotly.link"
}
Leave out slug for a random back-half. Add "domain": "go.yourbrand.com" to use a connected branded domain.
3. Endpoints
| Request | What it does |
|---|---|
GET/account | Plan, this month's usage and API calls left |
GET/links?q=&limit=50&before_id= | Your links, newest first. Page with next_before_id |
POST/links | Create: url, optional slug, title, tags, domain, expires_at (Unix time), active |
GET/links/{id} | One link |
PATCH/links/{id} | Change url, slug, title, tags, expires_at or active |
DELETE/links/{id} | Delete a link (it stops working) |
GET/links/{id}/stats?days=30 | Totals, daily series, sources, countries, devices, OS, apps and shares, within your plan's history |
GET/links/{id}/leads | Leads from a link's lead form |
4. Limits and errors
Each request uses one API call from your plan: Free 1,000, Pro 100,000 and Business 500,000 a month. Up to 300 requests a minute per key. Every response has an X-Quota-Remaining header. Creating links counts toward your monthly link allowance, the same as in the dashboard.
| Status | Meaning |
|---|---|
401 | Missing, wrong or revoked key |
402 | Your plan doesn't include this, or the monthly link allowance is used up (upgrade names the plan that does) |
404 | No such link in this workspace |
409 | That back-half is taken |
422 | Something in the request isn't allowed, for example an unsafe destination |
429 | Too many requests a minute, or this month's API calls are used up |
{"error": {"code": "plan_limit", "message": "You've used all 30 short links on Free this month.", "upgrade": "pro"}}
Keys belong to a workspace, not a person. Revoke a key in Settings and it stops working straight away.