API Evolution & Deprecations

We evolve our API through additive changes and predictable deprecations — not versioned URLs. This ensures your integrations remain stable while allowing us to improve the API.

---

What's a Breaking Change?

Breaking Changes

Require your code to be updated:

• Removing or renaming endpoints, fields, or parameters
• Changing data types or formats
• Making optional fields required
• Tightening validation rules

Non-Breaking Changes

Work with your existing code:

• Adding new endpoints or fields
• Adding optional parameters
• Loosening validation
• Performance improvements

---

The Deprecation Timeline

When we need to make a breaking change, we follow a predictable process:

1

Announce Deprecation

We mark the feature as deprecated in our API responses and in our documentation. Your code continues to work normally.

2

Migration Period (6+ months)

Both old and new approaches work side-by-side. We provide migration guides and send email notifications.

3

Removal at Fixed Date

The deprecated feature is removed only on a fixed date: Jan 15, Apr 15, Jul 15, or Oct 15 (23:59:59 UTC). This gives you a predictable timeline to plan for a migration.

Example:

Consider a field deprecated on 2026-01-01. The field will be removed on 2026-07-15 (6 months + rounded to the next allowed removal date)

        2026-01-01                                                    2026-07-15
            │                                                              │
            ▼                                                              ▼
────────────●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━●────────────
            │                                                              │
 Deprecation Introduced                                         Deprecation Removed

            ├──────────────────── Migration Period ────────────────────────┤

---

How You'll Know About Changes

API Headers

Every response using deprecated features includes an X-Glean-Deprecated header with full details.

Documentation

Inline warnings on API pages, migration guides, and a complete deprecation schedule.

When you use a deprecated feature, the API response includes an X-Glean-Deprecated header:

X-Glean-Deprecated: kind=field;name=snippetText;introduced=2026-01-01;removal=2026-07-15;docs=https://developers.glean.com/deprecations

The header contains:

Field	Description
kind	Type of deprecation: endpoint, field, or parameter
name	Name of the deprecated item
introduced	Date the deprecation was announced (ISO-8601)
removal	Date the item will be removed (ISO-8601)
docs	Link to migration documentation

Automated Monitoring

Parse this header in your integration tests or monitoring to catch deprecations early.

---

Testing Future Changes

Validate your integration before deprecated features are removed by including the X-Glean-Exclude-Deprecated-After header:

X-Glean-Exclude-Deprecated-After: 2027-01-15

This header simulates how the API will behave after the deprecation date, helping you verify your code handles the changes correctly.

---

After Removal

When deprecated items are removed, the API provides clear error responses:

Item Type	Response
Endpoints	410 Gone with migration instructions
Request fields	400 Bad Request with details
Response fields	Simply omitted from the response

Example error response

{
  "error": {
    "code": "deprecated_field_removed",
    "message": "Field 'userId' was removed on 2027-01-15. Use 'userIdentifier' instead.",
    "docs": "https://developers.glean.com/docs/migrations/2027-01-15"
  }
}