smoooch REST API v1
Server-to-server API for a smoooch workspace: read landing pages, direct links and stats, and create, change and delete direct links — for a tool that uses smoooch as its link provider.
- Base URL:
https://smoooch.bio/api/v1 - JSON in, JSON out (
Content-Type: application/jsonon requests with a body). - Available on the plans that include API access (see /pricing).
Authentication
Every request carries a workspace API key:
Authorization: Bearer sb_live_…
Keys are made on the API page of the app (/app/developers, owners and admins only). The full key is shown once; smoooch stores only its hash. A key sees exactly one workspace.
| Access | Can do |
|---|---|
| Read only | every GET |
| Read and write | every GET, plus POST, PATCH and DELETE on direct links |
Rules:
- Call the API only from a server. Never put a key in a browser, an app or a repository — store it as a secret. smoooch sends no CORS headers, so browsers on other sites cannot call the API.
- A revoked key, or a workspace whose plan no longer includes the API, stops working at once (401 / 402).
- Each change made with a key is written to the workspace's activity log with the key's prefix.
Errors and limits
Errors are JSON with a 4xx status:
{ "error": "That address is taken. Try another slug.", "field": "slug" }
| Status | Meaning |
|---|---|
| 400 | Invalid input. field names the field (destination, slug, title, ageGate, enabled, days). |
| 401 | Missing, wrong or revoked key. |
| 402 | The plan does not include the API, or the workspace is at its plan's link limit ("code": "plan_limit"). |
| 403 | The key is read-only and the request writes. |
| 404 | Not found — or it belongs to another workspace (they look the same). |
| 409 | The address (slug) is taken. |
| 429 | Too many requests: at most 600 a minute per calling IP address. Wait and retry. |
Responses are never cached (Cache-Control: no-store). Times are ISO 8601 in UTC; days are YYYY-MM-DD in UTC.
Link limits per workspace (landing pages and direct links together) follow the workspace's plan.
Direct links
A direct link is an address on smoooch — https://smoooch.bio/<slug> — that sends the visitor to a destination. smoooch handles the rest by itself: it opens the phone's real browser or the right app where it can, shows its "Open in browser" screen inside apps that block that (TikTok, Snapchat, Instagram …), and shows an 18+ page first when ageGate is on. The destination never appears in the link's HTML.
Landing pages and direct links share one namespace: a slug is taken if either uses it.
The direct link object
{
"id": 42,
"slug": "promo-day",
"url": "https://smoooch.bio/promo-day",
"destination": "https://example.com/offer",
"title": "Promo",
"groupId": null,
"ageGate": false,
"enabled": true,
"createdAt": "2026-10-03T12:00:00.000Z",
"updatedAt": "2026-10-03T12:00:00.000Z"
}
| Field | Type | Notes |
|---|---|---|
id | integer | Use it in the paths below. |
slug | string | 3–30 characters: a–z, 0–9, ., -, _; not at the start or end, no ../--. Stored lower-case. Some names are reserved. |
url | string | The address to share. |
destination | string | http:// or https:// only. |
title | string | Up to 100 characters; only shown inside smoooch. |
groupId | number or null | The group the link is in. |
ageGate | boolean | Show the 18+ page first. |
enabled | boolean | false: the address answers 404 until it is switched on again. |
POST /direct-links — create (Read and write)
Body — only destination is required:
{ "destination": "https://example.com/offer", "slug": "promo-day", "title": "Promo", "ageGate": false }
- Without
slug(or withnull/""), smoooch picks a free 7-character one, likek7m2qpx. 201 Createdwith the direct link object.409if the slug is taken,402at the plan's link limit.
curl -X POST https://smoooch.bio/api/v1/direct-links \
-H "Authorization: Bearer $SMOOOCH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"destination":"https://example.com/offer","slug":"promo-day"}'
GET /direct-links — list
{ "data": [ <direct link>, … ] }, newest first. ?slug=promo-day returns only that one (or an empty list).
GET /direct-links/:id — one link
The direct link object, or 404.
PATCH /direct-links/:id — change (Read and write)
Send only what changes: any of destination, slug, title, ageGate, enabled. Returns the updated object. Changing slug changes the address; the old one stops working (409 if the new one is taken).
{ "destination": "https://example.com/new-offer", "enabled": true }
DELETE /direct-links/:id — delete (Read and write)
204 No Content. The address is free again, and the link's stats are deleted with it — a new link on the same address starts from zero.
GET /names/:name — is an address free?
{ "name": "promo-day", "available": true }
{ "name": "a", "available": false, "reason": "Use 3–30 characters: …" }
Free now does not guarantee free at creation: always handle 409 on POST.
GET /direct-links/:id/stats?days=30 — views and clicks
days is 1 or more (default 30), capped by the plan's history.
- views — everyone who opened the link: on its 18+ page, on the "Open in browser" screen inside an app, or straight on.
uniquesare different people per day among them. - clicks — those who got all the way out to the destination in the real browser or app. A visitor who stays inside Instagram, Facebook or TikTok is a view without a click.
- rate — clicks per view, in percent.
Bots, link-preview crawlers and the workspace's own signed-in members are not counted.
{
"from": "2026-09-04",
"to": "2026-10-03",
"totals": { "views": 120, "uniques": 97, "clicks": 88, "rate": 73.3 },
"series": [ { "date": "2026-09-04", "views": 3, "uniques": 3, "clicks": 2 }, … ],
"breakdown": {
"source": [ { "value": "instagram", "count": 61 }, … ],
"country": [ { "value": "SE", "count": 40 }, … ],
"device": [ { "value": "mobile", "count": 110 }, … ],
"app": [], "os": [], "browser": [], "language": [], "hour": []
},
"clickBreakdown": { "source": [ … ], … }
}
series has one entry per day, zeros included. breakdown is for views, clickBreakdown for clicks; each list is sorted by count, highest first; hour values are 00–23 UTC.
Using smoooch as a link provider
- Key — in smoooch, create a key with Read and write access and store it as a secret.
- Check it —
GET /workspacereturns the workspace, its plan and limits. - Create —
POST /direct-linkswith the destination. Keep the returnedidandurl; showurlto the user. - Retries without duplicates —
POSTis not idempotent. If you choose the slug yourself, a retry that gets409can look it up withGET /direct-links?slug=…: if it is listed, it is yours (created by the first attempt). Without your own slug, a timed-out request may have made a link; list and comparedestinationbefore trying again. - Update / remove —
PATCHorDELETE /direct-links/:id. A link deleted in the smoooch app returns404: treat that as gone. - Clicks —
GET /direct-links/:id/stats?days=…, orGET /statsfor every link at once. Poll sparingly (stats change per visit; once every few minutes is plenty).
Other read endpoints (any key)
| Endpoint | Returns |
|---|---|
GET /workspace | { id, name, plan, limits, usage } — limits.links is the plan's link limit, usage.links how many are in use (also seats, domains). |
GET /pages | { data: [ { id, handle, url, title, bio, layout, groupId, ageGate, createdAt, updatedAt } ] } — published landing pages. |
GET /pages/:id | A page with items (its links and blocks) and socials. |
GET /pages/:id/stats?days=30 | totals (views, uniques, clicks, ctr), series, clicks per link in items, breakdown for views and clickBreakdown for clicks. |
GET /items/:id/stats?days=30 | One link on a landing page: totals { clicks, uniques }, series, breakdown. |
GET /stats?days=30 | The whole workspace: totals, series, per landing page (pages) and per direct link (smartLinks: [ { id, slug, views, uniques, clicks } ]), breakdown, clickBreakdown. |
GET /live?minutes=60 | The last 30 or 60 minutes per minute (series), with the busiest pages, links and direct links. ?target=link:<id> narrows to one direct link. |
Groups
A link is in one group or none — a model, a creator, a client. Landing pages and direct links both carry groupId (a group's id, or null).
| Endpoint | |
|---|---|
GET /groups | { data: [ { id, name } ] } |
POST /groups (Read and write) | { "name": "Nova" } → 201 { id, name }. At most 50 groups. |
PATCH /groups/:id (Read and write) | { "name": "…" } renames it. |
DELETE /groups/:id (Read and write) | Deletes the group; its links stay, in no group. |
PATCH /pages/:id (Read and write) | { "groupId": 3 } or { "groupId": null } puts a landing page into a group. |
For a direct link, send groupId with POST /direct-links or PATCH /direct-links/:id.
Revenue (Fanvue)
When a workspace has connected Fanvue (Revenue in the app), every link that leads to a connected creator's Fanvue profile is tracked, and these endpoints give what the links earned. Money is in USD cents: net is what the creator keeps after Fanvue's fee, gross is before it. Numbers come from Fanvue about every 15 minutes.
How it is counted: a fan belongs to the first smoooch link they came in through; everything they pay after that click counts for that link, with the source, country and device of that first visit. A fan who was already subscribed when they clicked is left out. Refunds and chargebacks are taken off. No fan names or ids are given out — only totals.
GET /revenue — what the links earned
Period: ?days=30 (default), or ?from=2026-10-01&to=2026-10-31 (UTC days). Narrow it with creatorId, directLinkId, pageId or itemId (a button on a landing page).
{
"from": "2026-10-01", "to": "2026-10-31", "currency": "USD", "unit": "cents",
"totals": { "net": 188400, "gross": 235500, "payingFans": 43, "payments": 112, "fans": 108, "subscribers": 54, "followers": 97, "clicks": 4210 },
"previous": { "net": 150200, "gross": 187750, "payingFans": 35, "payments": 90, "fans": 80, "subscribers": 41, "followers": 70, "clicks": 3900 },
"allEarnings": { "net": 264000, "gross": 330000 },
"daily": [ { "date": "2026-10-01", "net": 6400, "gross": 8000, "payments": 4, "allNet": 9100, "allGross": 11375 } ],
"links": [ { "type": "direct-link", "id": 12, "name": "nova-ig", "url": "https://smoooch.bio/nova-ig", "groupId": 3, "deleted": false,
"net": 102400, "gross": 128000, "payingFans": 22, "payments": 60, "fans": 60, "subscribers": 27, "followers": 55, "clicks": 2400 } ],
"sources": [ { "source": "instagram", "net": 69985, "gross": 87480, "payingFans": 17, "payments": 44, "fans": 41, "subscribers": 20, "followers": 37 } ],
"countries": [ { "country": "US", "net": 49191, "…": "…" } ],
"devices": [ { "device": "mobile", "…": "…" } ],
"systems": [ { "system": "ios", "…": "…" } ],
"browsers": [ { "browser": "in-app", "…": "…" } ],
"types": [ { "type": "message", "net": 71600, "gross": 89500, "payments": 34 } ],
"creators": [ { "creatorId": 1, "net": 188400, "…": "…" } ]
}
totals.fansare new fans who came in through the links in the period;subscribersthose of them who subscribed;payingFansthe fans whose payments fall in the period.clicksare the clicks on the tracked smoooch links (sonet / clicksis revenue per click).previousis the same for the period just before, as long.allEarningsis everything the connected creators' fans paid in the period, tracked or not —totals.net / allEarnings.netis the share that came through smoooch links.links[].typeisdirect-linkorpage(a landing page, all its buttons together).groupIdis the link's group — with one group per model, summing bygroupIdgives revenue per model.- Values:
sourceis a name likeinstagram,tiktok,reddit,twitter,direct, or a hostname;countrya two-letter code;devicemobile/desktop/tablet;systemios/android/windows/macos/…;browserin-app/safari/chrome/…; any of them can beunknown.typeis Fanvue's kind of payment:subscription,renewal,message,post,tip,refund,chargeback, …
GET /revenue/accounts — what is connected
{
"connections": [ { "id": 1, "handle": "nova", "name": "Nova", "status": "ok", "connectedAt": "…", "syncedAt": "…",
"creators": [ { "id": 1, "handle": "nova", "name": "Nova", "managed": false, "tracking": true, "syncedAt": "…", "error": null } ] } ],
"trackingLinks": [ { "creatorId": 1, "directLinkId": 12, "pageId": null, "itemId": null, "name": "smoooch · /nova-ig",
"url": "https://www.fanvue.com/nova/fv-3",
"fanvue": { "clicks": 420, "subscribers": 27, "followers": 55, "gross": 128000, "net": 102400 } } ]
}
status is ok, or reconnect / scopes when the person has to connect Fanvue again in smoooch (links stay tracked meanwhile; numbers stop arriving). managed creators come through an agency seat. trackingLinks[].fanvue are Fanvue's own totals for that tracking link, for comparison — Fanvue counts by its own rules, so they can differ from /revenue. Connecting and disconnecting Fanvue is done by a person in the app, not over the API.
Applications connected with OAuth
Our own applications do not use an API key: a person connects their workspace and the application gets an access token (sb_oat_…) that works on every endpoint here, reading and writing, whatever the workspace's plan. That is described in Connect with OAuth, with three more endpoints for the connection itself: GET /connection, PUT/DELETE /connection/grant and DELETE /connection.
/smart-links and /smart-links/:id/stats are older names for /direct-links and still work.
Keys are made in the app, under API.