Response structure

Every TEASE endpoint speaks the same dialect: JSON in, JSON out, the same error shape, the same status codes, and the same pagination contract. This page documents those conventions once so each endpoint page can focus on the fields that are unique to it.

Format

• Every response is application/json, including errors. There is no XML, form, or protobuf encoding.
• Requests that send a body must set Content-Type: application/json. A malformed or non-JSON body is rejected with 400.
• Authentication is a bearer token on every request — see Authentication. A request with no valid token never reaches the resource and returns 401.
• Field names are snake_case. Money values are decimal numbers in the account currency (for example 2370.50), not integer cents.
• Successful reads return either a single resource object or a list of resource objects. Mutations return the resulting resource (or, where there is nothing to return, an empty body with a 2xx status).

{
  "provider_id": "lnk_8fq2",
  "name": "instagram-bio",
  "active": true,
  "created_at": 1751280000
}

Timestamps

All timestamps are Unix epoch seconds (UTC) — a plain integer, never a string and never milliseconds — unless a field is explicitly documented otherwise.

To render one, multiply by 1000 for JavaScript Date, or divide nothing for most other languages:

const created = new Date(resource.created_at * 1000);

from datetime import datetime, timezone

created = datetime.fromtimestamp(resource["created_at"], tz=timezone.utc)

Errors

Errors use the appropriate HTTP status code and a small, predictable JSON body with two fields:

{
  "error": "invalid_scope",
  "message": "Invalid scope values: ['admin']. Allowed: ['read', 'write']"
}

The golden rule: switch on the HTTP status and the error code, never on the message text. The message is for humans and may change wording at any time; the status and error code are the contract.

HTTP status codes

The API uses standard HTTP semantics. Every endpoint draws from this table; individual reference pages call out any status that carries a special meaning for that route.

Reading an error in code

const res = await fetch(url, { headers });
if (!res.ok) {
  const { error, message } = await res.json();
  // branch on `error`, not on `message`
  if (res.status === 429) return backoffAndRetry();
  if (error === 'invalid_scope') throw new Error('use a write-scoped key');
  throw new Error(`${res.status} ${error}: ${message}`);
}
const data = await res.json();

res = requests.get(url, headers=headers)
if not res.ok:
    body = res.json()
    error, message = body["error"], body["message"]
    if res.status_code == 429:
        return backoff_and_retry()
    if error == "invalid_scope":
        raise RuntimeError("use a write-scoped key")
    raise RuntimeError(f"{res.status_code} {error}: {message}")
data = res.json()

Pagination

Some list endpoints accept a limit parameter to bound how many items come back in one response. Where an endpoint paginates, its exact parameters appear on its reference page — there is no single pagination scheme you can assume applies everywhere, so always read the endpoint you are calling.

Two rules keep your client correct regardless of which scheme a given endpoint uses:

1. Page until the result set is exhausted rather than assuming a fixed page size. The server may return fewer items than your limit even when more pages remain.
2. Treat a cursor as opaque. Its contents are an implementation detail and may change; never parse, edit, or persist meaning into it. Store only "the next cursor I was given."

// Cursor-based: follow the cursor until it stops coming back.
let cursor: string | undefined;
const all = [];
do {
  const url = new URL('https://app.tease.link/api/admin/inbox/conversations');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await (await fetch(url, { headers })).json();
  all.push(...page.items);
  cursor = page.next_cursor; // undefined / null when exhausted
} while (cursor);

# Offset-based: advance until a short page tells you you're done.
limit, offset, all_items = 100, 0, []
while True:
    page = requests.get(
        "https://app.tease.link/api/admin/vault/search",
        headers=headers,
        params={"limit": limit, "offset": offset},
    ).json()
    items = page["items"]
    all_items.extend(items)
    if len(items) < limit:
        break
    offset += limit

Next steps

• Authentication — mint and use an al_live_* token.
• Rate limits — what 429 means and how to back off.
• API Reference — the exact fields for every endpoint.