intercom · Eclairemoy · Apr 11, 2026 · Apr 10, 2026
diff --git a/.claude/skills/generate-openapi-from-pr/SKILL.md b/.claude/skills/generate-openapi-from-pr/SKILL.md
@@ -88,7 +88,7 @@ Look for:
 #### 3d. Version Registration (`app/lib/api/versioning/service.rb`)
 
 Look for which version block the new change is added to:
-- `UnstableVersion.new(changes: [...])` → goes in Unstable (version `0/`)
+- `PreviewVersion.new(changes: [...])` → goes in Preview (version `0/`)
 - `Version.new(id: "2.15", changes: [...])` → goes in that specific version
 
 #### 3e. Routes (`config/routes/api_v3.rb`)
@@ -113,11 +113,11 @@ I found the following API changes in PR #XXXXX:
 - [list of changes found]
 
 Which API versions should I update?
-- Unstable only (default for new features)
+- Preview only (default for new features)
 - Specific versions (for bug fixes/backports)
 ```
 
-Default to Unstable (`descriptions/0/api.intercom.io.yaml`) unless the PR clearly targets specific versions.
+Default to Preview (`descriptions/0/api.intercom.io.yaml`) unless the PR clearly targets specific versions.
 
 ### Step 5: Read Target Spec File(s)
 
@@ -194,9 +194,9 @@ Report to the user:
 Always remind the user of remaining manual steps:
 
 1. **Review generated changes** for accuracy against the actual API behavior
-2. **Fern overrides** — if new endpoints were added to Unstable, check if `fern/unstable-openapi-overrides.yml` needs SDK method name entries
+2. **Fern overrides** — if new endpoints were added to Preview, check if `fern/preview-openapi-overrides.yml` needs SDK method name entries
 3. **Developer-docs PR** — copy the updated spec to the `developer-docs` repo:
-   - Copy `descriptions/0/api.intercom.io.yaml` → `docs/references/@Unstable/rest-api/api.intercom.io.yaml`
+   - Copy `descriptions/0/api.intercom.io.yaml` → `docs/references/@Preview/rest-api/api.intercom.io.yaml`
    - For stable versions: `descriptions/2.15/api.intercom.io.yaml` → `docs/references/@2.15/rest-api/api.intercom.io.yaml`
 4. **Changelog** — if the change should appear in the public changelog, update `docs/references/@<version>/changelog.md` in the developer-docs repo (newest entries at top)
 5. **Cross-version changes** — if this is an unversioned change (affects all versions), also update `docs/build-an-integration/learn-more/rest-apis/unversioned-changes.md` in developer-docs

diff --git a/.claude/skills/generate-openapi-from-pr/ruby-to-openapi-mapping.md b/.claude/skills/generate-openapi-from-pr/ruby-to-openapi-mapping.md
@@ -350,13 +350,13 @@ class TicketsController < OauthAuthenticatedController
 end
 ```
 
-This means: the entire endpoint only exists in versions that include `AddTicketsApi`. Add the endpoint to the Unstable spec (or whichever version includes the change).
+This means: the entire endpoint only exists in versions that include `AddTicketsApi`. Add the endpoint to the Preview spec (or whichever version includes the change).
 
 ### Version Registration Location
 
 ```ruby
 # In app/lib/api/versioning/service.rb
-UnstableVersion.new(changes: [
+PreviewVersion.new(changes: [
   Changes::AddNewFeature,    # → add to descriptions/0/
 ])
 

diff --git a/.claude/skills/generate-openapi-from-pr/version-propagation.md b/.claude/skills/generate-openapi-from-pr/version-propagation.md
@@ -6,7 +6,7 @@ How to decide which API version spec files to update and how to propagate change
 
 | Version | Directory | Notes |
 |---|---|---|
-| Unstable | `descriptions/0/` | All new features land here first |
+| Preview | `descriptions/0/` | All new features land here first |
 | 2.15 | `descriptions/2.15/` | Current latest stable |
 | 2.14 | `descriptions/2.14/` | Stable SDK source (used by Fern) |
 | 2.13 | `descriptions/2.13/` | |
@@ -23,9 +23,9 @@ Each version file is independent — always check the actual `intercom_version`
 
 ### 1. New Feature (most common)
 
-**Update: Unstable only** (`descriptions/0/api.intercom.io.yaml`)
+**Update: Preview only** (`descriptions/0/api.intercom.io.yaml`)
 
-If the PR adds the version change to `UnstableVersion` in the versioning service, only update the Unstable spec. This is the case for ~95% of API changes.
+If the PR adds the version change to `PreviewVersion` in the versioning service, only update the Preview spec. This is the case for ~95% of API changes.
 
 ### 2. Bug Fix to Existing Documentation
 
@@ -35,11 +35,11 @@ If the PR fixes a bug in how an existing field/endpoint is documented (wrong typ
 
 ### 3. Feature Promoted to Stable Version
 
-**Update: Target version + all later versions + Unstable**
+**Update: Target version + all later versions + Preview**
 
 If the PR adds a version change to a specific numbered version (e.g., `Version.new(id: "2.15")`), update that version and all later versions. Features in a numbered version are also in all subsequent versions.
 
-Example: Change added to 2.14 → update 2.14, 2.15, and Unstable.
+Example: Change added to 2.14 → update 2.14, 2.15, and Preview.
 
 ### 4. Backport to Older Versions
 
@@ -53,17 +53,17 @@ Rare. If the PR explicitly mentions backporting, update all specified versions.
 
 Each version's spec has a different enum for `intercom_version`:
 
-**Unstable** includes all versions plus `Unstable`:
+**Preview** includes all versions plus `Preview`:
 ```yaml
 intercom_version:
-  example: Unstable
-  default: Unstable
+  example: Preview
+  default: Preview
   enum:
   - '1.0'
   - '1.1'
   # ... all versions ...
   - '2.14'
-  - Unstable
+  - Preview
 ```
 
 **Stable versions** include all versions up to and including themselves:
@@ -85,9 +85,9 @@ Note: Stable specs set `default` to the previous stable version and do NOT inclu
 
 Each spec has a different `info.version`:
 ```yaml
-# Unstable
+# Preview
 info:
-  version: Unstable
+  version: Preview
 
 # v2.15
 info:
@@ -96,33 +96,33 @@ info:
 
 ### Available Endpoints
 
-Unstable has endpoints that don't exist in stable versions. When adding an endpoint to Unstable, do NOT add it to stable versions unless the corresponding version change is registered in that version's change list.
+Preview has endpoints that don't exist in stable versions. When adding an endpoint to Preview, do NOT add it to stable versions unless the corresponding version change is registered in that version's change list.
 
 ### Schema Differences
 
-Some schemas have additional fields in Unstable that don't exist in stable versions. When propagating a fix, be careful not to add Unstable-only fields to stable versions.
+Some schemas have additional fields in Preview that don't exist in stable versions. When propagating a fix, be careful not to add Preview-only fields to stable versions.
 
 ## Propagation Checklist
 
 When updating multiple versions:
 
-1. **Start with Unstable** — make the change in `descriptions/0/api.intercom.io.yaml`
+1. **Start with Preview** — make the change in `descriptions/0/api.intercom.io.yaml`
 2. **Copy to each target version** — replicate the same change in each version file
 3. **Verify consistency** — ensure the change makes sense in context of each version (don't add references to schemas that don't exist in older versions)
 4. **Check intercom_version** — do NOT modify the `intercom_version` enum unless explicitly adding a new API version
-5. **Run validation** — `fern check` validates the spec used by Fern (currently v2.14 + Unstable), but manually review other versions
+5. **Run validation** — `fern check` validates the spec used by Fern (currently v2.14 + Preview), but manually review other versions
 
 ## Fern Validation Scope
 
 `fern check` only validates:
 - `descriptions/2.14/api.intercom.io.yaml` (stable SDK source)
-- `descriptions/0/api.intercom.io.yaml` (unstable SDK source)
+- `descriptions/0/api.intercom.io.yaml` (preview SDK source)
 
 Changes to other version files (2.7-2.13, 2.15) are NOT validated by Fern. Be extra careful with YAML syntax in those files.
 
 ## Fern Overrides
 
-When adding new endpoints to Unstable, you may need to add entries to `fern/unstable-openapi-overrides.yml` for SDK method naming:
+When adding new endpoints to Preview, you may need to add entries to `fern/preview-openapi-overrides.yml` for SDK method naming:
 
 ```yaml
 paths:

diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -11,4 +11,4 @@ List all API versions that are affected by these changes.
 For example:
 - v2.0
 - v2.13
-- Unstable
+- Preview
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -9,11 +9,11 @@ Owner: `team-data-foundations` (see `REPO_OWNER`)
 ```
 descriptions/
   2.7/ ... 2.15/            # Stable versioned API specs (one YAML each)
-  0/                         # Unstable version (version "0" internally)
+  0/                         # Preview version (version "0" internally)
 fern/
   generators.yml             # SDK generation config (TS, Java, Python, PHP)
   openapi-overrides.yml      # Fern overrides for stable spec (v2.14)
-  unstable-openapi-overrides.yml  # Fern overrides for Unstable
+  preview-openapi-overrides.yml  # Fern overrides for Preview
   fern.config.json           # Fern org config
 scripts/
   run-sync.js                # Entry point for spec upload (CI only)
@@ -94,14 +94,14 @@ When a change applies to multiple API versions, you must edit each version's YAM
 ### Version Numbering
 
 - Stable versions: `2.7`, `2.8`, ..., `2.15` (current latest)
-- Unstable: stored as `descriptions/0/` (mapped from "Unstable" in upload scripts)
+- Preview: stored as `descriptions/0/` (mapped from "Preview" in upload scripts)
 - Every endpoint requires an `Intercom-Version` header parameter
 
 ## SDK Generation (Fern)
 
 SDKs are generated from the spec using [Fern](https://buildwithfern.com/). The `fern/generators.yml` configures:
 - **Stable SDK source**: `descriptions/2.14/api.intercom.io.yaml` (note: v2.14, not v2.15)
-- **Unstable SDK source**: `descriptions/0/api.intercom.io.yaml` (namespace: `unstable`)
+- **Preview SDK source**: `descriptions/0/api.intercom.io.yaml` (namespace: `preview`)
 
 ### DANGER: Never run `fern generate` without `--preview` locally
 

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
@@ -2,7 +2,7 @@
 openapi: 3.0.1
 info:
   title: Intercom API
-  version: Unstable
+  version: Preview
   description: The intercom API reference.
   contact:
     name: Intercom Developer Hub
@@ -9907,7 +9907,7 @@ paths:
           in: header
           required: true
           schema:
-            $ref: '#/components/schemas/intercom_version_unstable'
+            $ref: '#/components/schemas/intercom_version_preview'
       requestBody:
         required: true
         content:
@@ -9950,7 +9950,7 @@ paths:
           in: header
           required: true
           schema:
-            $ref: '#/components/schemas/intercom_version_unstable'
+            $ref: '#/components/schemas/intercom_version_preview'
       requestBody:
         required: true
         content:
@@ -10002,7 +10002,7 @@ paths:
           in: header
           required: true
           schema:
-            $ref: '#/components/schemas/intercom_version_unstable'
+            $ref: '#/components/schemas/intercom_version_preview'
       requestBody:
         required: true
         content:
@@ -10054,7 +10054,7 @@ paths:
           in: header
           required: true
           schema:
-            $ref: '#/components/schemas/intercom_version_unstable'
+            $ref: '#/components/schemas/intercom_version_preview'
       requestBody:
         required: true
         content:
@@ -12078,8 +12078,8 @@ paths:
 
         This endpoint is designed for EU Data Act compliance, allowing customers to export their workflow configurations.
 
-        {% admonition type="warning" name="Unstable API" %}
-          This API is currently in the Unstable version. Its behavior may change in future releases.
+        {% admonition type="warning" name="Preview API" %}
+          This API is currently in the Preview version. Its behavior may change in future releases.
         {% /admonition %}
       responses:
         '200':
@@ -12277,14 +12277,14 @@ paths:
             curl -X GET 'https://api.intercom.io/macros?per_page=25&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd' \
               -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
               -H 'Accept: application/json' \
-              -H 'Intercom-Version: @Unstable'
+              -H 'Intercom-Version: @Preview'
         - lang: 'Node.js'
           source: |
             const response = await fetch('https://api.intercom.io/macros?per_page=25&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd', {
               headers: {
                 'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>',
                 'Accept': 'application/json',
-                'Intercom-Version': '@Unstable'
+                'Intercom-Version': '@Preview'
               }
             });
             const macros = await response.json();
@@ -12295,7 +12295,7 @@ paths:
             headers = {
                 'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>',
                 'Accept': 'application/json',
-                'Intercom-Version': '@Unstable'
+                'Intercom-Version': '@Preview'
             }
 
             params = {
@@ -12325,7 +12325,7 @@ paths:
             request = Net::HTTP::Get.new(uri)
             request['Authorization'] = 'Bearer <YOUR_ACCESS_TOKEN>'
             request['Accept'] = 'application/json'
-            request['Intercom-Version'] = '@Unstable'
+            request['Intercom-Version'] = '@Preview'
 
             response = http.request(request)
             macros = JSON.parse(response.body)
@@ -12550,14 +12550,14 @@ paths:
             curl -X GET 'https://api.intercom.io/macros/123' \
               -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
               -H 'Accept: application/json' \
-              -H 'Intercom-Version: @Unstable'
+              -H 'Intercom-Version: @Preview'
         - lang: 'Node.js'
           source: |
             const response = await fetch('https://api.intercom.io/macros/123', {
               headers: {
                 'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>',
                 'Accept': 'application/json',
-                'Intercom-Version': '@Unstable'
+                'Intercom-Version': '@Preview'
               }
             });
             const macro = await response.json();
@@ -12568,7 +12568,7 @@ paths:
             headers = {
                 'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>',
                 'Accept': 'application/json',
-                'Intercom-Version': '@Unstable'
+                'Intercom-Version': '@Preview'
             }
 
             response = requests.get('https://api.intercom.io/macros/123',
@@ -12587,7 +12587,7 @@ paths:
             request = Net::HTTP::Get.new(uri)
             request['Authorization'] = 'Bearer <YOUR_ACCESS_TOKEN>'
             request['Accept'] = 'application/json'
-            request['Intercom-Version'] = '@Unstable'
+            request['Intercom-Version'] = '@Preview'
 
             response = http.request(request)
             macro = JSON.parse(response.body)
@@ -25379,8 +25379,8 @@ components:
       description: Intercom API version.</br>By default, it's equal to the version
         set in the app package.
       type: string
-      example: Unstable
-      default: Unstable
+      example: Preview
+      default: Preview
       enum:
       - '1.0'
       - '1.1'
@@ -25402,7 +25402,7 @@ components:
       - '2.12'
       - '2.13'
       - '2.14'
-      - Unstable
+      - Preview
     linked_object:
       title: Linked Object
       type: object
@@ -25429,13 +25429,13 @@ components:
           -
           example: Customer
           nullable: true
-    intercom_version_unstable:
-      description: Unstable Intercom API version. Used for closed beta endpoints or other features under managed availability.
+    intercom_version_preview:
+      description: Preview Intercom API version. Used for closed beta endpoints or other features under managed availability.
       type: string
-      example: unstable
-      default: unstable
+      example: preview
+      default: preview
       enum:
-        - unstable
+        - preview
     linked_object_list:
       title: Linked Objects
       type: object

diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml
@@ -16271,7 +16271,7 @@ components:
       - '2.9'
       - '2.10'
       - '2.11'
-      - Unstable
+      - Preview
     linked_object:
       title: Linked Object
       type: object

diff --git a/fern/generators.yml b/fern/generators.yml
@@ -14,8 +14,8 @@ api:
         coerce-optional-schemas-to-nullable: true
         coerce-enums-to-literals: true
     - openapi: ../descriptions/0/api.intercom.io.yaml
-      overrides: ./unstable-openapi-overrides.yml
-      namespace: unstable
+      overrides: ./preview-openapi-overrides.yml
+      namespace: preview
       settings:
         title-as-schema-name: false
         inline-path-parameters: true

diff --git a/fern/openapi-overrides.yml b/fern/openapi-overrides.yml
@@ -2369,7 +2369,7 @@ x-fern-version:
     - "2.12"
     - "2.13"
     - "2.14"
-    - "Unstable"
+    - "Preview"
 
 servers:
   - url: https://api.intercom.io/
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,4 +11,4 @@ List all API versions that are affected by these changes. @@
     For example:
     - v2.0
     - v2.13
-    - Unstable
+    - Preview