# 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/json` on requests with a body).
- Available on the plans that include API access (see [/pricing](https://smoooch.bio/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:

```json
{ "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

```json
{
  "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](#groups) 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:

```json
{ "destination": "https://example.com/offer", "slug": "promo-day", "title": "Promo", "ageGate": false }
```

- Without `slug` (or with `null` / `""`), smoooch picks a free 7-character one, like `k7m2qpx`.
- `201 Created` with the direct link object.
- `409` if the slug is taken, `402` at the plan's link limit.

```bash
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).

```json
{ "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?

```json
{ "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. `uniques` are 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.

```json
{
  "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

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)

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

```json
{
  "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.fans` are new fans who came in through the links in the period; `subscribers` those of them who subscribed; `payingFans` the fans whose payments fall in the period. `clicks` are the clicks on the tracked smoooch links (so `net / clicks` is revenue per click).
- `previous` is the same for the period just before, as long.
- `allEarnings` is everything the connected creators' fans paid in the period, tracked or not — `totals.net / allEarnings.net` is the share that came through smoooch links.
- `links[].type` is `direct-link` or `page` (a landing page, all its buttons together). `groupId` is the link's group — with one group per model, summing by `groupId` gives revenue per model.
- Values: `source` is a name like `instagram`, `tiktok`, `reddit`, `twitter`, `direct`, or a hostname; `country` a two-letter code; `device` `mobile`/`desktop`/`tablet`; `system` `ios`/`android`/`windows`/`macos`/…; `browser` `in-app`/`safari`/`chrome`/…; any of them can be `unknown`. `type` is Fanvue's kind of payment: `subscription`, `renewal`, `message`, `post`, `tip`, `refund`, `chargeback`, …

### `GET /revenue/accounts` — what is connected

```json
{
  "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](/docs/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.
