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.

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.

AccessCan do
Read onlyevery GET
Read and writeevery GET, plus POST, PATCH and DELETE on direct links

Rules:

Errors and limits

Errors are JSON with a 4xx status:

{ "error": "That address is taken. Try another slug.", "field": "slug" }
StatusMeaning
400Invalid input. field names the field (destination, slug, title, ageGate, enabled, days).
401Missing, wrong or revoked key.
402The plan does not include the API, or the workspace is at its plan's link limit ("code": "plan_limit").
403The key is read-only and the request writes.
404Not found — or it belongs to another workspace (they look the same).
409The address (slug) is taken.
429Too 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.

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.

{
  "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"
}
FieldTypeNotes
idintegerUse it in the paths below.
slugstring3–30 characters: a–z, 0–9, ., -, _; not at the start or end, no ../--. Stored lower-case. Some names are reserved.
urlstringThe address to share.
destinationstringhttp:// or https:// only.
titlestringUp to 100 characters; only shown inside smoooch.
groupIdnumber or nullThe group the link is in.
ageGatebooleanShow the 18+ page first.
enabledbooleanfalse: 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 }
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"}'

{ "data": [ <direct link>, … ] }, newest first. ?slug=promo-day returns only that one (or an empty list).

The direct link object, or 404.

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 }

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.

days is 1 or more (default 30), capped by the plan's history.

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.

  1. Key — in smoooch, create a key with Read and write access and store it as a secret.
  2. Check it — GET /workspace returns the workspace, its plan and limits.
  3. Create — POST /direct-links with the destination. Keep the returned id and url; show url to the user.
  4. Retries without duplicates — POST is not idempotent. If you choose the slug yourself, a retry that gets 409 can look it up with GET /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 compare destination before trying again.
  5. Update / remove — PATCH or DELETE /direct-links/:id. A link deleted in the smoooch app returns 404: treat that as gone.
  6. Clicks — GET /direct-links/:id/stats?days=…, or GET /stats for every link at once. Poll sparingly (stats change per visit; once every few minutes is plenty).

Other read endpoints (any key)

EndpointReturns
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/:idA page with items (its links and blocks) and socials.
GET /pages/:id/stats?days=30totals (views, uniques, clicks, ctr), series, clicks per link in items, breakdown for views and clickBreakdown for clicks.
GET /items/:id/stats?days=30One link on a landing page: totals { clicks, uniques }, series, breakdown.
GET /stats?days=30The whole workspace: totals, series, per landing page (pages) and per direct link (smartLinks: [ { id, slug, views, uniques, clicks } ]), breakdown, clickBreakdown.
GET /live?minutes=60The 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.

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, "…": "…" } ]
}

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.