> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/api-developer-tools.md).

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

<div data-with-frame="true"><figure><img src="https://3931781085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjvxfJkYMGfMfN4qlzl0C%2Fuploads%2FRlb7HkLtgVWTml80zEBC%2Fimage.png?alt=media&amp;token=ff4ff559-3630-411b-aca2-eeeb50b01a11" alt="FullSession API Tokens settings page showing obfuscated tokens and the &#x22;Create New Token&#x22; action."><figcaption></figcaption></figure></div>

***

### 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](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610), [4](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610), [7](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610) |
| **Integrations** (Intercom, HubSpot, Optimizely, Zapier…) | FullSession ↔ third parties | Connect to specific tools                  | [Chapter 19](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610)                                                                                                                                                       |
| **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.

<div data-with-frame="true"><figure><img src="https://3931781085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjvxfJkYMGfMfN4qlzl0C%2Fuploads%2FOVcR7xpgKsHEkws6gfS8%2Fimage.png?alt=media&amp;token=1e4c4230-3b69-4158-abc3-94170f521811" alt="FullSession token creation screen showing name, optional description, and site scope options for &#x22;All&#x22; or &#x22;Specific Sites&#x22;."><figcaption></figcaption></figure></div>

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

<figure><img src="https://3931781085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjvxfJkYMGfMfN4qlzl0C%2Fuploads%2F4GHItkJsaerdGLdc4inB%2Fimage.png?alt=media&amp;token=ab75cfee-5efa-42d1-8b68-22c9ef5253b6" alt="FullSession one-time token reveal showing the full API token value to copy, with only the obfuscated version visible afterward."><figcaption></figcaption></figure>

#### 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

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

```json
{
  "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](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610) & [19](https://claude.ai/epitaxy/local_f5f6ba49-6bd2-4e30-b58d-b88360e08610)) — 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.