📘

API documentation

This page describes the ShortBoost API for AI assistants and automations. You create a key under API keys.

Basics

Address: https://api.shortboost.one/api/v1
Authentication: header Authorization: Bearer sbo_live_… (never as a URL parameter)
Format: JSON, for POST/PATCH with Content-Type: application/json
Limit: 60 requests per minute per key
First call: GET /key-info shows account, plan, permissions and number of links

curl -H "Authorization: Bearer sbo_live_…" https://api.shortboost.one/api/v1/key-info

Links

Call	Permission	Purpose
`GET /links`	links.read	List. Parameters: `page`, `limit` (max. 100), `search`, `project_id`, `category_id` (`none` = without), `favorite=true`, `sort` (`created_desc`, `created_asc`, `clicks_desc`, `clicks_asc`, `name_asc`, `name_desc`)
`GET /links/{id}`	links.read	a single link
`GET /links/check-slug/{slug}`	links.read	is the short address available? `{"available":true}`
`GET /links/{id}/qr`	links.read	QR code. Parameters: `format=png\|svg`, `size` (100–1000), `color`, `bg` (hex without #)
`POST /links`	links.write	create. Required: `original_url`. Optional: `slug`, `title`, `name`, `notes`, `tags` (list), `project_id`, `category_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `expires_at`, `click_limit`, `password`, `smart_routing` (list of rules, see below)
`PATCH /links/{id}`	links.write	update, same fields as when creating, plus `is_active`, `is_favorite`
`POST /links/bulk`	links.write (for `delete` also links.delete)	`{"action":"activate\|deactivate\|move\|categorize\|favorite\|delete","link_ids":[…],"payload":{…}}`, max. 500 links
`DELETE /links/{id}`	links.delete	delete

curl -X POST https://api.shortboost.one/api/v1/links \
  -H "Authorization: Bearer sbo_live_…" \
  -H "Content-Type: application/json" \
  -d '{"original_url":"https://example.com/angebot","title":"Herbstangebot","utm_source":"newsletter"}'

Response (shortened):

{"link":{"id":"…","slug":"aB3xY9","short_url":"https://shlk.one/aB3xY9","original_url":"https://example.com/angebot","title":"Herbstangebot","click_count":0,"has_password":false,"smart_routing":[],"is_active":true,"created_at":"…"}}

Smart routing (`smart_routing`)

With smart routing, a link sends visitors to a different destination depending on country, language, operating system or device. The rules are checked from top to bottom and the first match wins. If none matches, original_url applies. More in the article Smart routing. Only on the Pro and Lifetime plans (otherwise 402).

Field per rule	Meaning
`url`	Required. Destination of this rule, `http://` or `https://`
`name`	optional, max. 60 characters (appears in the statistics)
`country`	Countries as uppercase ISO codes, e.g. `["AT","DE","CH"]`
`language`	Browser language as lowercase ISO code, e.g. `["de","en"]`
`os`	`ios`, `android`, `windows`, `macos`, `linux`
`device`	`mobile`, `tablet`, `desktop`
`id`	assigned by the server. Leave it out for new rules, send it back unchanged for existing ones, otherwise the statistics of this rule start over

Every rule needs a url and at least one condition. Conditions are combined with AND, multiple values within one condition with OR. An empty condition means "any".
At most 10 rules per link. The order of the list is the order they are checked in.
PATCH with smart_routing replaces all rules. [] or null deletes all rules. Without the field they stay unchanged.
In responses, smart_routing is always a list, shown as [] when there are no rules.

Example: an app link that sends iPhones to the App Store and Android devices to Google Play. Everyone else lands on the website.

curl -X PATCH https://api.shortboost.one/api/v1/links/{id}   -H "Authorization: Bearer sbo_live_…"   -H "Content-Type: application/json"   -d '{"original_url":"https://example.com/app",
       "smart_routing":[
         {"name":"iPhone","url":"https://apps.apple.com/app/id123456789","os":["ios"]},
         {"name":"Android","url":"https://play.google.com/store/apps/details?id=com.example.app","os":["android"]}
       ]}'

Statistics

Call	Purpose
`GET /analytics/overview?days=30`	Total clicks, links, top links
`GET /analytics/dashboard`	Metrics, clicks per day, browsers, sources, devices, countries. Parameters `from`, `to` (ISO date)
`GET /analytics/links/{id}`	Analysis of one link, same parameters. Contains `routing`: clicks per smart routing rule, e.g. `[{"route_id":"a1b2c3d4e5","clicks":12},{"route_id":null,"clicks":40}]`. `route_id` is the `id` of the rule, `null` means: no rule matched (normal destination)
`GET /analytics/clicks?days=30`	Clicks over time
`GET /analytics/geo?days=30`	Countries and cities
`GET /analytics/devices?days=30`	Devices, browsers, operating systems
`GET /analytics/utm?days=30`	UTM sources, mediums, campaigns
`GET /analytics/heatmap`, `/analytics/heatmap/{id}`	Clicks by weekday and time of day

All statistics calls require stats.read.

Projects and categories

Call	Permission
`GET /projects`, `GET /categories` (optional `?project_id=`)	projects.read
`POST /projects` `{"name":"…","color":"#1a56db"}`, `POST /categories` `{"name":"…","project_id":"…"}`	projects.write
`PATCH /projects/{id}`, `PATCH /categories/{id}`	projects.write
`DELETE /projects/{id}` (links move to the default project), `DELETE /categories/{id}`	projects.delete

Errors

Status	Response	Meaning
401	`{"error":"invalid_key"}`	Key is invalid, revoked or expired, or the call is not available through the API
402	`{"error":"plan_required"}`	Account does not have (or no longer has) a Pro or Lifetime plan
403	`{"error":"missing_scope","required":"links.write"}`	the key lacks this permission
429	`{"error":"rate_limited"}`	more than 60 requests per minute; the `Retry-After` header gives the wait time in seconds
400, 404, 409	`{"error":"…"}`	application error with a German message, e.g. "Slug bereits vergeben"

Instruction for an AI

You control my link shortener ShortBoost via the API https://api.shortboost.one/api/v1
with the header "Authorization: Bearer <KEY>". Documentation: https://shortboost.one/help/api-dokumentation
1. First call GET /key-info and check your permissions.
2. Create links with POST /links and give me the short_url back.
3. Do not delete anything without my explicit confirmation.
4. On a 429, wait the number of seconds given in the Retry-After header.

‹ Back to the help overview