Quick start
The base URL is https://soa.plus/api/v1. Send a URL, get a short link back:
curl -X POST https://soa.plus/api/v1/links \
-H 'Content-Type: application/json' \
-d '{"url": "https://soldoutafrica.com/events/some-long-event-name"}'
HTTP/1.1 201 Created
Location: /api/v1/links/k7Pq2x
{
"slug": "k7Pq2x",
"short_url": "https://soa.plus/k7Pq2x",
"target_url": "https://soldoutafrica.com/events/some-long-event-name",
"tag": "LINK",
"active": true,
"created_at": "2026-11-20T09:14:03.512Z",
"qr_url": "https://soa.plus/qr/k7Pq2x.png",
"clicks": 0,
"guest_token": "spg_9rQ…"
}
The link is live immediately. Because no credentials were sent, the API made you a
guest and returned its guest_token. Keep it: it's the only way to
read that link's clicks or delete it later.
Authentication
Send a token as a Bearer header. There are two kinds, and one endpoint that needs neither.
Authorization: Bearer spk_… # an account's API key
Authorization: Bearer spg_… # a guest token
| Caller | How | Can do |
|---|---|---|
| Anonymous | No header | Create a link (POST /links). Each call mints a new guest and returns its token. |
| Guest | spg_… from a create response |
Create more links under the same guest, list them, read stats and clicks, delete. No custom slugs, no editing. |
| Account | spk_… from your API keys |
Everything: custom slugs, edits, pausing links, the higher link limit. |
401 — it never falls
back to anonymous, so a typo'd key can't quietly scatter your links across new guests.
The API ignores cookies and sessions entirely, and any origin may call it (CORS is open),
so never put an account key in code that ships to browsers.Guests who later create an account in the browser keep their browser links. Links made through the API under a guest token stay with that token.
Limits
| Limit | Value | Response |
|---|---|---|
| Requests | 120 a minute per key, guest token or IP | 429 rate_limited |
| Guest link creation | 15 an hour, 60 a day per network | 429 rate_limited |
| Links per guest | 50 | 403 limit_reached |
| Links per account | 500 | 403 limit_reached |
| API keys per account | 10 active | 403 limit_reached |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining
and X-RateLimit-Reset (seconds). A 429 also carries
Retry-After.
Errors
Errors use the HTTP status and one body shape. code is stable — branch on it;
message is written for people and may change.
{
"error": {
"code": "slug_taken",
"message": "soa.plus/launch is already taken."
}
}
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Bad URL, slug, range or cursor; missing fields. |
| 400 | invalid_json | The body isn't valid JSON. |
| 401 | unauthorized | The endpoint needs a token and none was sent. |
| 401 | invalid_token | The token is malformed, unknown or revoked. |
| 403 | account_required | Custom slugs and edits need an account. |
| 403 | limit_reached | A link or key quota is full. |
| 404 | not_found | No such link among yours, or no such endpoint. |
| 409 | slug_taken | Someone already has that custom slug. |
| 415 | invalid_request | Send JSON with Content-Type: application/json. |
| 429 | rate_limited | Too many requests, or too many guest links from your network. |
The link object
| Field | Type | Notes |
|---|---|---|
slug | string | The path after the domain. Case-sensitive. |
short_url | string | The full short link to share. |
target_url | string | Where it redirects. Always http or https. |
tag | string | Free label, upper-cased, up to 32 characters. Default LINK. |
active | boolean | Paused links answer 404 instead of redirecting. |
created_at | string | ISO-8601, UTC. |
qr_url | string | PNG QR code for the link. Scans are counted as QR traffic. |
clicks | integer | All-time clicks, bots excluded. |
guest_token | string | Only on an anonymous create. Shown once. |
Create a link
/linksNo auth needed| Body field | Notes | |
|---|---|---|
url | required | The destination. A missing scheme means https. Links to private or internal addresses, and back to this domain, are refused. |
slug | accounts only | Your own path: letters, numbers, - and _,
up to 64 characters. Leave it out for a random 6-character one. |
tag | optional | A label for your own filtering, e.g. INSTAGRAM. |
curl -X POST https://soa.plus/api/v1/links \
-H "Authorization: Bearer $SOA_PLUS_KEY" \
-H 'Content-Type: application/json' \
-d '{"url": "https://soldoutafrica.com/events/afro-nights", "slug": "afro-nights", "tag": "instagram"}'
Returns 201 with the link object and a Location header.
To keep adding links to the same guest, send its guest_token as the Bearer token —
otherwise every anonymous call starts a new guest.
List links
/linksKey or guest token| Query | Default | Notes |
|---|---|---|
limit | 50 | 1–500. |
offset | 0 | Newest first. |
curl https://soa.plus/api/v1/links?limit=20 -H "Authorization: Bearer $SOA_PLUS_KEY"
{
"data": [
{ "slug": "afro-nights", "short_url": "https://soa.plus/afro-nights", "clicks": 1204, … }
],
"total": 37,
"limit": 20,
"offset": 0
}
Get a link
/links/{slug}Key or guest tokenReturns the link object with its all-time clicks. Only your own links are visible —
anyone else's slug is a 404, the same as one that doesn't exist.
Update a link
/links/{slug}Account keySend any of url, tag and active; anything left out stays
as it is. The slug can't change — create a new link instead. Changes reach the redirect
within a minute.
curl -X PATCH https://soa.plus/api/v1/links/afro-nights \
-H "Authorization: Bearer $SOA_PLUS_KEY" \
-H 'Content-Type: application/json' \
-d '{"url": "https://soldoutafrica.com/events/afro-nights-2", "active": true}'
Guests get 403 account_required: a shared link that silently changes destination
is how short links get abused, so only an account can do it.
Delete a link
/links/{slug}Key or guest tokenReturns 204. The link and its whole click history are gone, and the slug
becomes free for anyone to take. The short link stops redirecting within a minute. To stop a link without losing its history,
set active to false instead.
Link stats
/links/{slug}/statsKey or guest token| Query | Default | Notes |
|---|---|---|
range | 30d | 24h (hourly buckets), 7d, 30d
(daily) or 90d (weekly). Buckets follow the service's time zone, which the response names. |
Everything the dashboard shows for one link, as numbers. Bots are counted in
bot_hits and left out of everything else.
{
"slug": "afro-nights",
"range": "7d",
"from": "2026-11-13T21:00:00Z",
"to": "2026-11-20T21:00:00Z",
"timezone": "Africa/Nairobi",
"clicks": 412,
"unique_visitors": 301,
"returning_clicks": 64,
"bot_hits": 9,
"previous_period_clicks": 350,
"change_pct": 17.7,
"busiest_hour": 20,
"also_on_your_other_links": 41,
"timeseries": [
{ "start": "2026-11-14T00:00:00+03:00", "clicks": 38 },
…
],
"devices": [ { "name": "Mobile", "clicks": 351, "pct": 85.2 }, … ],
"browsers": [ { "name": "Chrome Mobile", "clicks": 190, "pct": 46.1 }, … ],
"operating_systems": [ { "name": "Android", "clicks": 260, "pct": 63.1 }, … ],
"countries": [ { "country": "Kenya", "cities": ["Nairobi", "Mombasa"], "clicks": 380, "pct": 92.2 }, … ],
"referrers": [ { "name": "Instagram", "kind": "Social", "host": "l.instagram.com", "clicks": 150, "pct": 36.4 }, … ]
}
change_pct compares with the window before; it's null when that window had
no clicks. busiest_hour is 0–23 in the service's time zone, or null.
also_on_your_other_links counts this link's visitors who also clicked another of your links.
Click events
/links/{slug}/clicksKey or guest token| Query | Default | Notes |
|---|---|---|
limit | 50 | 1–500. |
cursor | The next_cursor from the previous page. |
Individual clicks, newest first, bots excluded. Page through with next_cursor until it's
null; new clicks arriving meanwhile never shift your pages.
{
"data": [
{
"clicked_at": "2026-11-20T17:42:10.031Z",
"visitor_id": "3f0c9a1e5b7d4c2a8e6f1b0d9c7a5e3f",
"new_visitor": false,
"country_code": "KE",
"country": "Kenya",
"city": "Nairobi",
"device_type": "Mobile",
"browser": "Chrome Mobile",
"browser_version": "131",
"os": "Android",
"os_version": "14",
"source": "Instagram",
"referrer_host": "l.instagram.com",
"qr_scan": false,
"utm_source": "ig",
"utm_medium": "story",
"utm_campaign": "afro-nights",
"language": "en-KE"
}
],
"next_cursor": "MTczMjEyNDUzMDAzMTAwMDo4ODQx"
}
visitor_id is a salted pseudonym: stable for one person across your links, meaningless
anywhere else. IP addresses are never returned.
QR codes
https://soa.plus/qr/{slug}.pngPublicA PNG QR code for any active link — the qr_url on the link object. It encodes the short
link with ?qr=1, so scans show up as qr_scan: true and as
“Direct / QR scan” in the referrers.
Who am I
/meKey or guest tokenHandy for checking a token and your remaining room.
{
"type": "guest",
"email": null,
"display_name": null,
"created_at": "2026-11-20T09:14:03.402Z",
"links": 3,
"link_limit": 50,
"custom_slugs": false,
"edit_links": false
}
OpenAPI spec
The full contract is an OpenAPI 3.1 document at https://soa.plus/api/v1/openapi.yaml. Import it into Postman, Insomnia or a client generator, or browse it in the interactive reference, where you can send requests from the page.