SOA.PLUS
Sign in Create account
REST API · v1

Short links from your own code.

Create a link with one request — no account, no key. Add a key when you want to manage links and read the same analytics the dashboard shows. JSON in, JSON out.

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
CallerHowCan 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.
A header that's present but wrong is always a 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

LimitValueResponse
Requests120 a minute per key, guest token or IP 429 rate_limited
Guest link creation15 an hour, 60 a day per network 429 rate_limited
Links per guest50403 limit_reached
Links per account500403 limit_reached
API keys per account10 active403 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."
  }
}
StatuscodeMeaning
400invalid_requestBad URL, slug, range or cursor; missing fields.
400invalid_jsonThe body isn't valid JSON.
401unauthorizedThe endpoint needs a token and none was sent.
401invalid_tokenThe token is malformed, unknown or revoked.
403account_requiredCustom slugs and edits need an account.
403limit_reachedA link or key quota is full.
404not_foundNo such link among yours, or no such endpoint.
409slug_takenSomeone already has that custom slug.
415invalid_requestSend JSON with Content-Type: application/json.
429rate_limitedToo many requests, or too many guest links from your network.

Create a link

POST/linksNo auth needed
Body fieldNotes
urlrequiredThe destination. A missing scheme means https. Links to private or internal addresses, and back to this domain, are refused.
slugaccounts onlyYour own path: letters, numbers, - and _, up to 64 characters. Leave it out for a random 6-character one.
tagoptionalA 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

GET/linksKey or guest token
QueryDefaultNotes
limit501–500.
offset0Newest 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

GET/links/{slug}Key or guest token

Returns 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

PATCH/links/{slug}Account key

Send 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

DELETE/links/{slug}Key or guest token

Returns 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

GET/links/{slug}/statsKey or guest token
QueryDefaultNotes
range30d24h (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

GET/links/{slug}/clicksKey or guest token
QueryDefaultNotes
limit501–500.
cursorThe 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

GEThttps://soa.plus/qr/{slug}.pngPublic

A 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

GET/meKey or guest token

Handy 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.