20. API & Developer Tools

FullSession exposes a small, focused REST API for pulling your session data into your own systems, authenticated with API tokens you generate in the app. This chapter covers creating and managing tokens, the one available endpoint, authentication, rate limits, and — importantly — where the API's boundaries are.

API tokens are managed under Settings → API Tokens, governed by the api_tokens:view, api_tokens:create, and api_tokens:delete permissions ([Chapter 16 — Team & Account Management]).

---

20.1 What the API Offers

Set expectations first: FullSession's public API is intentionally narrow. It provides one read-only endpoint — listing sessions for a site — authenticated by a token scoped to one or more of your sites.

It helps to know where the API fits among FullSession's three developer-facing surfaces, which are easy to confuse:

Surface	Direction	Purpose	Where it's covered
Tracker SDK (FUS.identify, FUS.event, …)	Browser → FullSession	Send identity, events, and attributes in	Chapters 3, 4, 7
Integrations (Intercom, HubSpot, Optimizely, Zapier…)	FullSession ↔ third parties	Connect to specific tools	Chapter 19
REST API (this chapter)	FullSession → your code	Pull session data out	This chapter

If you're looking to send data in, that's the tracker SDK ([Chapter 3, section 3.5]). The REST API is only for reading session data out.

---

20.2 API Tokens

API tokens authenticate your requests. You can create multiple tokens, each scoped to specific sites.

Creating a token

1. Click Create New Token (requires api_tokens:create).

2. Provide:

   • Token name (required) — must be unique.

   • Description (optional).

   • Permissions — choose All (every site in your account) or Specific Sites (pick the sites this token may access).

3. Click Create.

Copy it now — it's shown only once

When the token is created, FullSession displays the full token value once, with the message "You will only see the token ONCE, so make sure to copy it now." Copy it immediately and store it securely. Afterward, the app only ever shows an obfuscated form (e.g. fus_****abc) — the full value can't be retrieved again.

Token scope

Tokens are scoped by site, not by action:

Scope	Access
All	Any site in your account
Specific Sites	Only the sites you selected

Tokens are not granularly scoped. There are no "read-only" vs. "write" or per-resource scopes — within its site scope, a token can call the available endpoint. (The API itself is read-only, so a token can only read sessions.)

Managing tokens

Action	Available?
Create multiple tokens	✅
List your tokens (obfuscated)	✅
Delete / revoke a token	✅
Edit a token's name/description	❌ Not supported
Regenerate a token (keep the name)	❌ Not supported
Expiration / TTL	❌ Tokens don't expire
Last-used tracking	❌ Not tracked

Tokens are permanent until deleted, and don't expire. Treat each token like a password. To "rotate" a token, delete the old one and create a new one, then update your integration with the new value. Deleting a token immediately revokes its access.

---

20.3 The Sessions API

The single public endpoint lists sessions for one of your sites.

Endpoint

GET /v1/external/sessions/{customerId}/{siteId}

• {customerId} — your account's Customer ID.

• {siteId} — the site to read sessions from (the token must be scoped to this site).

Authentication

Pass your token as a Bearer token in the Authorization header:

Authorization: Bearer fus_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameters

All are optional:

Parameter	Meaning
startTime	Only sessions starting at/after this time (Unix milliseconds)
endTime	Only sessions ending at/before this time (Unix milliseconds)
startAfter	Pagination cursor — pass the value returned by the previous page

Example request

curl -H "Authorization: Bearer fus_xxxxxxxx..." \
  "https://<your FullSession API host>/v1/external/sessions/YOUR_CUSTOMER_ID/YOUR_SITE_ID?startTime=1717200000000&endTime=1717286400000"

Response

{
  "data": {
    "startAfter": 1717250000000,
    "sessions": [
      { "...session fields (id, user, pages, duration, timestamp, …)..." }
    ]
  }
}

Pagination

• The endpoint returns up to 1,000 sessions per request.

• To page through more, take the startAfter value from the response and pass it as the startAfter query parameter on your next call.

• Repeat until startAfter is no longer returned (you've reached the end).

1. GET …/sessions/{customerId}/{siteId}?startTime=…&endTime=…
2. Read data.startAfter from the response
3. GET …?startTime=…&endTime=…&startAfter=<that value>
4. Repeat until no startAfter is returned

Tip — drive bulk syncs by time window: page through a window with startTime/endTime, then advance the window. Keep each token's request volume within the rate limit (next section).

---

20.4 Rate Limits

The external API is rate-limited:

20 requests per minute across the /v1/external API.

This limit applies to the external API as a whole (it isn't tracked per individual token), so coordinate your jobs if several processes share access. Build in backoff and pacing so a bulk sync stays under the limit — combined with the 1,000-sessions-per-request page size, 20 requests/minute is enough to move a large volume of sessions steadily.

---

20.5 What the API Doesn't Include

To plan integrations accurately, know the boundaries. These don't exist:

• No other endpoints. The only public endpoint is list sessions (section 20.3). There's no API for funnels, segments, segment stats, dashboards/cards, events, or full-text session search.

• No programmatic data export. CSV export is a UI-only feature (from dashboard cards, capped at 10,000 rows — [Chapter 9, section 9.8]); there's no export-via-API.

• No developer webhooks. FullSession doesn't push events to your endpoints. Outbound automation goes through Zapier and the Slack alert hook (Chapters 15 & 19) — neither of which uses API tokens.

• No granular scopes, token expiry, regeneration, or last-used tracking (section 20.2).

• No in-app API reference or public OpenAPI/Swagger spec. Use this chapter as the reference for the available endpoint.

A note on the internal Dev Tools page

You may see a Settings → Dev Tools page referenced in the app. It's an internal FullSession support/impersonation tool, not a customer-facing developer feature — regular accounts don't have access to it, and it's unrelated to API tokens.

The big picture — FullSession's API is small and read-only: generate a site-scoped token under Settings → API Tokens (copy it once — it's shown only once and never expires), then call the single GET /v1/external/sessions/{customerId}/{siteId} endpoint with Authorization: Bearer fus_…, paging via startAfter at up to 1,000 sessions per request and 20 requests/minute. For sending data in, use the tracker SDK; for tool connections, use Integrations; for automation, use Zapier/alerts — none of which are part of this API.

---

Next up: [Chapter 21 — Privacy, Security & Compliance] covers what FullSession records and how to control it — masking, excluded users, IP and recording rules, and data retention.