From dba1cfc46d8dd557223158758a77ca3fd5a8a03d Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Thu, 23 Jul 2026 23:47:07 +0000
Subject: [PATCH 1/3] docs(openapi): describe user topic-preference fields
 explicitly (#172)

Add field descriptions to UsersTopicPreference and UsersTopicPreferenceUpdate
so the generated API reference documents them fully (topic_id, status,
default_status, has_custom_routing, custom_routing, topic_name), including the
REQUIRED-is-a-topic-default semantics and the custom_routing channel set. Wrap
the PreferenceStatus $ref fields in allOf so the description renders under
OpenAPI 3.0.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .stats.yml                         |  4 ++--
 src/resources/users/preferences.ts | 35 ++++++++++++++++++++++++++++--
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index e2794c7..e5f8121 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 134
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-b053468fefe6d757f86f3233ebbc52d80329ed2a6e7a6740fee01e4028a4c3b9.yml
-openapi_spec_hash: 416835e693de0fe19945be90a787d3f3
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-0630b37ff5ba795185e1e189b0f24d233ecd51681b6ebb7748cad8f0e8c4fcc0.yml
+openapi_spec_hash: b9a8c66633e914c9a2f7b3bf275c7349
 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7
diff --git a/src/resources/users/preferences.ts b/src/resources/users/preferences.ts
index decc312..b62fcee 100644
--- a/src/resources/users/preferences.ts
+++ b/src/resources/users/preferences.ts
@@ -216,19 +216,40 @@ export interface BulkPreferenceTopic {
 }
 
 export interface TopicPreference {
+  /**
+   * The topic's default status, returned on reads. It applies whenever the user has
+   * no override of their own (status equals this value).
+   */
   default_status: Shared.PreferenceStatus;
 
+  /**
+   * The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+   * user's own choice; REQUIRED is a topic-level default set in the preferences
+   * editor, not a user choice.
+   */
   status: Shared.PreferenceStatus;
 
+  /**
+   * The unique identifier of the subscription topic this preference applies to.
+   */
   topic_id: string;
 
+  /**
+   * The display name of the subscription topic, returned on reads.
+   */
   topic_name: string;
 
   /**
-   * The Channels a user has chosen to receive notifications through for this topic
+   * The channels the user has chosen to receive this topic on, present only when
+   * has_custom_routing is true. One or more of: direct_message, email, push, sms,
+   * webhook, inbox.
    */
   custom_routing?: Array<Shared.ChannelClassification> | null;
 
+  /**
+   * Whether the user has chosen specific delivery channels for this topic (listed in
+   * custom_routing) rather than the topic's default routing.
+   */
   has_custom_routing?: boolean | null;
 }
 
@@ -418,13 +439,23 @@ export interface PreferenceUpdateOrCreateTopicParams {
 
 export namespace PreferenceUpdateOrCreateTopicParams {
   export interface Topic {
+    /**
+     * The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+     * default, not a user choice; the API rejects opting a user out of a REQUIRED
+     * topic.
+     */
     status: Shared.PreferenceStatus;
 
     /**
-     * The Channels a user has chosen to receive notifications through for this topic
+     * The channels to deliver this topic on when has_custom_routing is true. One or
+     * more of: direct_message, email, push, sms, webhook, inbox.
      */
     custom_routing?: Array<Shared.ChannelClassification> | null;
 
+    /**
+     * Set to true to route this topic to the channels in custom_routing instead of the
+     * topic's default routing.
+     */
     has_custom_routing?: boolean | null;
   }
 }

From db95d94acdcfbf50bceb7282fc5cd393d539f7f9 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Sat, 25 Jul 2026 00:05:36 +0000
Subject: [PATCH 2/3] docs(openapi): rewrite operation descriptions for agents
 and SEO (#174)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrites the `description` on 116 of 134 operations and fills in 14 that had none
(GET /tenants, PUT /tenants/{id}, and other tenant/token/message operations). The 18
already-good descriptions are untouched.

Why: these descriptions feed the API reference, the generated llms.txt, and the SDK
docstrings across all seven languages. Many were either too terse to be useful to a
coding agent (e.g. "Returns the specified audience by id") or long enough that Mintlify
truncated them mid-sentence in llms.txt (10 sat at 300-301 chars). A prior SEO pass in
mintlify-docs (#563) was silently reverted by spec syncs because it edited the generated
mirror instead of this source file — this lands the work where it survives.

House style, applied uniformly:
- Sentence one states what the operation does using concrete nouns — actual response
  fields, enum values, and id formats, not vague paraphrase.
- Sentence two, when present, gives the reason to reach for it or the behavior that
  surprises people. No status codes, validation rules, em-dashes, or marketing adjectives
  (those live in the reference body).
- 95-160 characters, so they read fully in Google results and don't truncate in llms.txt.

Each description was written against the operation's schema (required params, response
properties, enums), not from assumption. This caught real errors: the message status
enum has 12 values and does not include UNDELIVERABLE; POST /auth/issue-token requires
both scope and expires_in (it is not "short-lived"); message content lives at
/messages/{id}/output.

Please give a domain check to three where behavior was inferred from HTTP semantics
rather than stated in the schema:
- PUT /users/{user_id}/tenants (users_tenants_addMultiple) — worded to only claim it
  adds; does it also remove tenants not listed in the body?
- PUT /notifications/{id}/{submissionId}/checks (replaceSubmissionChecks) — worded as
  "the complete set supplied"; are omitted checks dropped?
- GET /translations/{domain}/{locale} — says "notification content"; confirm the term.

Mechanical: only operation-level `description` lines changed (verified: 0 operationId
lines touched, 0 non-description lines added). Multi-line block scalars were collapsed to
single quoted lines, which accounts for the deletion count. openapi.yml still parses and
all 134 operations are intact.

Co-authored-by: Claude <noreply@anthropic.com>
---
 .stats.yml                                    |  4 +-
 src/resources/audiences.ts                    | 15 ++++--
 src/resources/audit-events.ts                 |  6 ++-
 src/resources/auth.ts                         |  3 +-
 src/resources/automations/automations.ts      |  3 +-
 src/resources/automations/invoke.ts           |  9 ++--
 src/resources/brands.ts                       | 16 +++---
 src/resources/digests/schedules.ts            |  5 +-
 src/resources/inbound.ts                      |  3 +-
 src/resources/journeys/journeys.ts            | 42 ++++++---------
 src/resources/journeys/templates.ts           | 28 +++++-----
 src/resources/lists/lists.ts                  | 15 ++++--
 src/resources/lists/subscriptions.ts          | 10 ++--
 src/resources/messages.ts                     | 26 +++++-----
 src/resources/notifications/checks.ts         |  9 ++--
 src/resources/notifications/notifications.ts  | 41 +++++++--------
 src/resources/profiles/lists.ts               | 10 ++--
 src/resources/profiles/profiles.ts            | 20 +++----
 src/resources/providers/catalog.ts            |  6 +--
 src/resources/providers/providers.ts          | 22 ++++----
 src/resources/requests.ts                     |  3 +-
 src/resources/routing-strategies.ts           |  8 +--
 src/resources/send.ts                         |  3 +-
 src/resources/tenants/preferences/items.ts    |  6 ++-
 src/resources/tenants/templates/templates.ts  | 29 ++++-------
 src/resources/tenants/templates/versions.ts   |  9 +---
 src/resources/tenants/tenants.ts              | 15 ++++--
 src/resources/translations.ts                 |  6 ++-
 src/resources/users/preferences.ts            | 52 +++++--------------
 src/resources/users/tenants.ts                | 20 +++----
 src/resources/users/tokens.ts                 | 18 ++++---
 src/resources/workspace-preferences/topics.ts | 17 +++---
 .../workspace-preferences.ts                  | 17 +++---
 33 files changed, 235 insertions(+), 261 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index e5f8121..48e4809 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 134
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-0630b37ff5ba795185e1e189b0f24d233ecd51681b6ebb7748cad8f0e8c4fcc0.yml
-openapi_spec_hash: b9a8c66633e914c9a2f7b3bf275c7349
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-5c878919b3df530781ebcd4ab1cda83606304da75c53fe0817d4c725d5bbbe73.yml
+openapi_spec_hash: dd37022222543ff064200e65e4b82f59
 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7
diff --git a/src/resources/audiences.ts b/src/resources/audiences.ts
index 2e2d99d..d92378a 100644
--- a/src/resources/audiences.ts
+++ b/src/resources/audiences.ts
@@ -9,14 +9,16 @@ import { path } from '../internal/utils/path';
 
 export class Audiences extends APIResource {
   /**
-   * Returns the specified audience by id.
+   * Returns one audience with its name, description, and the filter and AND or OR
+   * operator that decide which users belong to it.
    */
   retrieve(audienceID: string, options?: RequestOptions): APIPromise<Audience> {
     return this._client.get(path`/audiences/${audienceID}`, options);
   }
 
   /**
-   * Creates or updates audience.
+   * Creates or replaces an audience from a filter and an AND or OR operator.
+   * Membership recalculates automatically as profiles change.
    */
   update(
     audienceID: string,
@@ -27,7 +29,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get the audiences associated with the authorization token.
+   * Returns the audiences in the workspace with paging. Audiences are filter-based
+   * groups that recalculate as user profiles change.
    */
   list(
     query: AudienceListParams | null | undefined = {},
@@ -37,7 +40,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Deletes the specified audience.
+   * Deletes an audience permanently, so update any caller sending to it by audience
+   * id first. Those sends fail once the audience is gone.
    */
   delete(audienceID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/audiences/${audienceID}`, {
@@ -47,7 +51,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get list of members of an audience.
+   * Returns the users currently matching an audience filter, with paging. Membership
+   * is recalculated, so results shift as profiles change.
    */
   listMembers(
     audienceID: string,
diff --git a/src/resources/audit-events.ts b/src/resources/audit-events.ts
index 11c35fc..388bf70 100644
--- a/src/resources/audit-events.ts
+++ b/src/resources/audit-events.ts
@@ -8,14 +8,16 @@ import { path } from '../internal/utils/path';
 
 export class AuditEvents extends APIResource {
   /**
-   * Fetch a specific audit event by ID.
+   * Returns one audit event by id, including the actor who performed it, the target
+   * they changed, the source, the event type, and a timestamp.
    */
   retrieve(auditEventID: string, options?: RequestOptions): APIPromise<AuditEvent> {
     return this._client.get(path`/audit-events/${auditEventID}`, options);
   }
 
   /**
-   * Fetch the list of audit events
+   * Returns the workspace's audit event log with cursor paging. Each event records
+   * the actor, target, source, type, and timestamp of a change.
    */
   list(
     query: AuditEventListParams | null | undefined = {},
diff --git a/src/resources/auth.ts b/src/resources/auth.ts
index 0ce3ab1..6392e2f 100644
--- a/src/resources/auth.ts
+++ b/src/resources/auth.ts
@@ -6,7 +6,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Auth extends APIResource {
   /**
-   * Returns a new access token.
+   * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply
+   * the scope and an expires_in duration, both required.
    *
    * @example
    * ```ts
diff --git a/src/resources/automations/automations.ts b/src/resources/automations/automations.ts
index 6448ce7..51a3848 100644
--- a/src/resources/automations/automations.ts
+++ b/src/resources/automations/automations.ts
@@ -10,7 +10,8 @@ export class Automations extends APIResource {
   invoke: InvokeAPI.Invoke = new InvokeAPI.Invoke(this._client);
 
   /**
-   * Get the list of automations.
+   * Lists the workspace's saved automation templates, each with its id and a cursor
+   * for paging to the next page of results.
    *
    * @example
    * ```ts
diff --git a/src/resources/automations/invoke.ts b/src/resources/automations/invoke.ts
index dbfebed..487cff6 100644
--- a/src/resources/automations/invoke.ts
+++ b/src/resources/automations/invoke.ts
@@ -8,10 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Invoke extends APIResource {
   /**
-   * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a
-   * series of automation steps. For information about what steps are available,
-   * checkout the ad hoc automation guide
-   * [here](https://www.courier.com/docs/automations/steps/).
+   * Runs a series of automation steps supplied inline, without a saved template, and
+   * returns a runId.
    *
    * @example
    * ```ts
@@ -41,7 +39,8 @@ export class Invoke extends APIResource {
   }
 
   /**
-   * Invoke an automation run from an automation template.
+   * Starts an automation run from a saved template for one recipient, with optional
+   * data and profile, and returns a runId.
    *
    * @example
    * ```ts
diff --git a/src/resources/brands.ts b/src/resources/brands.ts
index c66441a..bb06c9e 100644
--- a/src/resources/brands.ts
+++ b/src/resources/brands.ts
@@ -10,8 +10,8 @@ import { path } from '../internal/utils/path';
 
 export class Brands extends APIResource {
   /**
-   * Create a new brand. Requires `name` and `settings` (with at least
-   * `colors.primary` and `colors.secondary`).
+   * Creates a brand from a name and settings, including primary and secondary
+   * colors. Brands supply the logo, colors, and styling that templates render with.
    *
    * @example
    * ```ts
@@ -28,7 +28,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Fetch a specific brand by brand ID.
+   * Returns one brand by id, including its colors, logo and styling settings,
+   * Handlebars snippets, and published version.
    *
    * @example
    * ```ts
@@ -40,7 +41,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Replace an existing brand with the supplied values.
+   * Replaces a brand with the values you supply, so send the complete settings and
+   * snippets rather than only the fields you want changed.
    *
    * @example
    * ```ts
@@ -54,7 +56,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Get the list of brands.
+   * Lists the workspace's brands. Every entry carries its name, styling settings,
+   * snippets, and published version.
    *
    * @example
    * ```ts
@@ -69,7 +72,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Delete a brand by brand ID.
+   * Deletes a brand by id. Reassign any template or tenant that references it before
+   * deleting to keep their styling intact.
    *
    * @example
    * ```ts
diff --git a/src/resources/digests/schedules.ts b/src/resources/digests/schedules.ts
index 671bd1d..1241183 100644
--- a/src/resources/digests/schedules.ts
+++ b/src/resources/digests/schedules.ts
@@ -9,9 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Schedules extends APIResource {
   /**
-   * List the digest instances for a schedule. Each instance represents the events
-   * accumulated for a single user against the schedule, and can be used to monitor
-   * digest accumulation before the digest is released.
+   * Returns the digest instances for a schedule, one per user, with cursor paging.
+   * Use it to see what has accumulated before a digest releases.
    */
   listInstances(
     scheduleID: string,
diff --git a/src/resources/inbound.ts b/src/resources/inbound.ts
index 56d5d27..b1318f8 100644
--- a/src/resources/inbound.ts
+++ b/src/resources/inbound.ts
@@ -6,7 +6,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Inbound extends APIResource {
   /**
-   * Courier Track Event
+   * Records an inbound event that can trigger a journey. Requires an event name, a
+   * messageId you generate, a type, and a properties object.
    *
    * @example
    * ```ts
diff --git a/src/resources/journeys/journeys.ts b/src/resources/journeys/journeys.ts
index 5704de1..82373c3 100644
--- a/src/resources/journeys/journeys.ts
+++ b/src/resources/journeys/journeys.ts
@@ -26,12 +26,8 @@ export class Journeys extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to
-   * publish on create. Send nodes are not allowed on `POST`. The standard flow is:
-   * create the journey shell here, add notification templates with
-   * `POST /journeys/{templateId}/templates`, then wire them into the journey with
-   * `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to
-   * publish a draft after the fact.
+   * Creates a journey from a set of nodes, in draft state unless you pass a
+   * published state. Send nodes cannot be included until their templates exist.
    *
    * @example
    * ```ts
@@ -72,7 +68,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Get the list of journeys.
+   * Lists the workspace's journeys, each carrying a name, state, and enabled flag.
+   * Paged by cursor.
    *
    * @example
    * ```ts
@@ -87,8 +84,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Archive a journey. Archived journeys cannot be invoked. Existing journey runs
-   * continue to completion.
+   * Archives a journey so it can no longer be invoked. Runs already in flight
+   * continue to completion, so archiving never strands a user mid-sequence.
    *
    * @example
    * ```ts
@@ -103,12 +100,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Cancel journey runs. The request body must include EXACTLY ONE of
-   * `cancelation_token` (cancels every run associated with the token) or `run_id`
-   * (cancels a single tenant-scoped run). Supplying both or neither returns a `400`.
-   * A `run_id` that does not match a run for the tenant returns `404`. Cancelation
-   * is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was
-   * already `CANCELED` is left unchanged and its current status is returned.
+   * Cancels in-flight journey runs, either every run sharing a cancelation token or
+   * one run by id. Use it to stop a sequence when the event resolves.
    *
    * @example
    * ```ts
@@ -122,8 +115,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Invoke a journey by id or alias to start a new run. The response includes a
-   * `runId` identifying the run.
+   * Starts a journey run for one user and returns a runId. Runs execute
+   * asynchronously, so the response arrives before any message is sent.
    *
    * @example
    * ```ts
@@ -145,7 +138,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * List published versions of a journey, ordered most recent first.
+   * Lists a journey's published versions, most recent first, so you have a version
+   * id to roll back to. Paged by cursor.
    *
    * @example
    * ```ts
@@ -158,9 +152,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Publish the current draft as a new version. Body is optional; pass
-   * `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if
-   * the journey has no draft to publish.
+   * Publishes a journey's current draft as a new version, making it live for new
+   * runs. Pass a version instead to roll back to an earlier one.
    *
    * @example
    * ```ts
@@ -176,11 +169,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Replace the journey draft. Updates the working draft only; call
-   * `POST /journeys/{templateId}/publish` to make it live, or pass
-   * `state: "PUBLISHED"` in this request to publish immediately. Send-node
-   * `template` ids must already exist and be scoped to this journey, and node ids
-   * must not be claimed by another journey.
+   * Replaces a journey's working draft, leaving the published version live until you
+   * publish. Reach for this when editing a journey already running.
    *
    * @example
    * ```ts
diff --git a/src/resources/journeys/templates.ts b/src/resources/journeys/templates.ts
index 8c0b489..6af914e 100644
--- a/src/resources/journeys/templates.ts
+++ b/src/resources/journeys/templates.ts
@@ -41,9 +41,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Fetch a journey-scoped notification template by id. Pass `?version=draft`
-   * (default `published`) to retrieve the working draft, or `?version=vN` for a
-   * historical version.
+   * Returns a journey's own notification template with its name, brand, subscription
+   * topic, and content. Defaults to the published version.
    *
    * @example
    * ```ts
@@ -81,8 +80,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Archive the journey-scoped notification template. Archived templates cannot be
-   * sent.
+   * Archives one journey's notification template, preventing further sends. Detach
+   * any send node referencing it beforehand.
    *
    * @example
    * ```ts
@@ -100,8 +99,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * List published versions of the journey-scoped notification template, ordered
-   * most recent first.
+   * Lists the published versions of a template that belongs to a journey, most
+   * recent first. Paged by cursor.
    *
    * @example
    * ```ts
@@ -121,9 +120,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Publish the current draft of the journey-scoped notification template as a new
-   * version. Optionally roll back to a prior version by passing
-   * `{ "version": "vN" }`.
+   * Publishes a journey-scoped template's draft as a new version. Pass a version
+   * instead to roll back the template to an earlier publish.
    *
    * @example
    * ```ts
@@ -201,7 +199,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Replace the journey-scoped notification template draft.
+   * Replaces the draft content of one journey's notification template. Publish it
+   * before send nodes referencing it render the change.
    *
    * @example
    * ```ts
@@ -228,11 +227,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Retrieve the elemental content of a journey-scoped notification template. The
-   * response contains the versioned elements along with their content checksums,
-   * which can be used to detect changes between versions. Pass `?version=draft`
-   * (default `published`) to retrieve the working draft, or `?version=vN` for a
-   * historical version.
+   * Returns the Elemental elements and version of a journey-scoped template's
+   * content. Compare versions to see what changed between publishes.
    *
    * @example
    * ```ts
diff --git a/src/resources/lists/lists.ts b/src/resources/lists/lists.ts
index 3967f26..55f40a5 100644
--- a/src/resources/lists/lists.ts
+++ b/src/resources/lists/lists.ts
@@ -21,14 +21,16 @@ export class Lists extends APIResource {
   subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this._client);
 
   /**
-   * Returns a list based on the list ID provided.
+   * Returns one list by id with its name and created and updated timestamps. Fetch
+   * its subscribers separately with the subscriptions endpoint.
    */
   retrieve(listID: string, options?: RequestOptions): APIPromise<SubscriptionList> {
     return this._client.get(path`/lists/${listID}`, options);
   }
 
   /**
-   * Create or replace an existing list with the supplied values.
+   * Creates or replaces a list from a name and preferences. Subscribers are managed
+   * through the separate subscriptions endpoints.
    */
   update(listID: string, body: ListUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}`, {
@@ -39,7 +41,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Returns all of the lists, with the ability to filter based on a pattern.
+   * Returns the workspace's lists, filterable by a pattern to fetch a subset such as
+   * every regional list. Paged by cursor.
    */
   list(
     query: ListListParams | null | undefined = {},
@@ -49,7 +52,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Delete a list by list ID.
+   * Deletes a list, halting sends that target it. A previously deleted list can be
+   * brought back with the companion restore endpoint.
    */
   delete(listID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/lists/${listID}`, {
@@ -59,7 +63,8 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Restore a previously deleted list.
+   * Restores a previously deleted list along with its subscribers, so a list removed
+   * by mistake can be brought back rather than rebuilt.
    */
   restore(listID: string, body: ListRestoreParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}/restore`, {
diff --git a/src/resources/lists/subscriptions.ts b/src/resources/lists/subscriptions.ts
index 4878bae..6993780 100644
--- a/src/resources/lists/subscriptions.ts
+++ b/src/resources/lists/subscriptions.ts
@@ -10,7 +10,8 @@ import { path } from '../../internal/utils/path';
 
 export class Subscriptions extends APIResource {
   /**
-   * Get the list's subscriptions.
+   * Returns the users subscribed to a list with paging, each with the preferences
+   * recorded for that subscription.
    */
   list(
     listID: string,
@@ -45,8 +46,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Subscribe a user to an existing list (note: if the List does not exist, it will
-   * be automatically created).
+   * Subscribes one user to a list, creating the list if it does not yet exist.
+   * Optional preferences apply to this subscription only.
    */
   subscribeUser(
     userID: string,
@@ -62,7 +63,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Delete a subscription to a list by list ID and user ID.
+   * Removes one user's subscription to a list, addressed by list id and user id. The
+   * user's profile and other subscriptions are separate resources.
    */
   unsubscribeUser(
     userID: string,
diff --git a/src/resources/messages.ts b/src/resources/messages.ts
index 4db8b9d..2acdf41 100644
--- a/src/resources/messages.ts
+++ b/src/resources/messages.ts
@@ -8,14 +8,16 @@ import { path } from '../internal/utils/path';
 
 export class Messages extends APIResource {
   /**
-   * Fetch the status of a message you've previously sent.
+   * Returns a sent message's status, recipient, event, and per-provider delivery
+   * detail, with timestamps for enqueued, sent, delivered, opened, and clicked.
    */
   retrieve(messageID: string, options?: RequestOptions): APIPromise<MessageRetrieveResponse> {
     return this._client.get(path`/messages/${messageID}`, options);
   }
 
   /**
-   * Fetch the statuses of messages you've previously sent.
+   * Returns previously sent messages, most recent first, each carrying its status,
+   * recipient, channel, and provider. Paged by cursor.
    */
   list(
     query: MessageListParams | null | undefined = {},
@@ -25,25 +27,24 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Cancel a message that is currently in the process of being delivered. A
-   * well-formatted API call to the cancel message API will return either `200`
-   * status code for a successful cancellation or `409` status code for an
-   * unsuccessful cancellation. Both cases will include the actual message record in
-   * the response body (see details below).
+   * Cancels a message that is still in the delivery pipeline and returns the message
+   * record with its resulting canceled or failed status.
    */
   cancel(messageID: string, options?: RequestOptions): APIPromise<MessageDetails> {
     return this._client.post(path`/messages/${messageID}/cancel`, options);
   }
 
   /**
-   * Get message content
+   * Returns the rendered content Courier delivered for a message, broken out per
+   * channel, to confirm what the recipient received.
    */
   content(messageID: string, options?: RequestOptions): APIPromise<MessageContentResponse> {
     return this._client.get(path`/messages/${messageID}/output`, options);
   }
 
   /**
-   * Fetch the array of events of a message you've previously sent.
+   * Returns the ordered event history for a sent message, one entry per status
+   * transition with its timestamp.
    */
   history(
     messageID: string,
@@ -54,11 +55,8 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Resend a previously sent message. The original send request is loaded from
-   * storage and a brand-new send is enqueued for the same recipient and content,
-   * producing a **new** `messageId` — the original message is not modified.
-   * Throttled by a per-message rate limit; a repeat inside the limit window returns
-   * `429 Too Many Requests`.
+   * Resends a previously sent message to the same recipient and content, returning a
+   * new messageId. The original send request is not modified.
    */
   resend(messageID: string, options?: RequestOptions): APIPromise<MessageResendResponse> {
     return this._client.post(path`/messages/${messageID}/resend`, options);
diff --git a/src/resources/notifications/checks.ts b/src/resources/notifications/checks.ts
index 490d838..29d683c 100644
--- a/src/resources/notifications/checks.ts
+++ b/src/resources/notifications/checks.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Checks extends APIResource {
   /**
-   * Replace the submission checks for a notification template.
+   * Replaces the approval checks on a template submission with the complete set
+   * supplied in the request body.
    *
    * @example
    * ```ts
@@ -38,7 +39,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * Retrieve the submission checks for a notification template.
+   * Returns the approval checks recorded for a template submission, each with its
+   * pass or fail result.
    *
    * @example
    * ```ts
@@ -58,7 +60,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * Cancel a submission for a notification template.
+   * Cancels a pending template submission, withdrawing it from the approval
+   * workflow. The template stays in draft and can be resubmitted later.
    *
    * @example
    * ```ts
diff --git a/src/resources/notifications/notifications.ts b/src/resources/notifications/notifications.ts
index 651726e..5d9efb2 100644
--- a/src/resources/notifications/notifications.ts
+++ b/src/resources/notifications/notifications.ts
@@ -69,7 +69,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * List notification templates in your workspace.
+   * Lists the workspace's notification templates. Each carries a name, tags, brand,
+   * routing, and its draft or published state.
    *
    * @example
    * ```ts
@@ -84,7 +85,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Archive a notification template.
+   * Archives a notification template, preventing new sends from referencing it. The
+   * template stays retrievable for its version history.
    *
    * @example
    * ```ts
@@ -99,12 +101,9 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Duplicate a notification template. Creates a standalone copy within the same
-   * workspace and environment, with " COPY" appended to the title. The copy clones
-   * the source draft's tags, brand, subscription topic, routing strategy, channels,
-   * and content, and is always created as a standalone template (it is not linked to
-   * any journey or broadcast, even if the source was). Templates that are scoped to
-   * a journey or a broadcast cannot be duplicated through this endpoint.
+   * Copies a notification template within the same workspace and environment,
+   * appending " COPY" to the title. The copy is standalone and independently
+   * editable.
    *
    * @example
    * ```ts
@@ -117,7 +116,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * List versions of a notification template.
+   * Returns a notification template's published versions, most recent first, for
+   * comparison or rollback. Paged.
    *
    * @example
    * ```ts
@@ -155,9 +155,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Replace the elemental content of a notification template. Overwrites all
-   * elements in the template with the provided content. Only supported for V2
-   * (elemental) templates.
+   * Replaces all Elemental content in a template, overwriting every existing
+   * element. Supported for V2 templates only, not V1 blocks and channels.
    *
    * @example
    * ```ts
@@ -180,8 +179,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Update a single element within a notification template. Only supported for V2
-   * (elemental) templates.
+   * Replaces one Elemental element in a template, addressed by its element id.
+   * Supported for V2 templates only, not V1 blocks and channels.
    *
    * @example
    * ```ts
@@ -204,9 +203,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Set locale-specific content overrides for a notification template. Each element
-   * override must reference an existing element by ID. Only supported for V2
-   * (elemental) templates.
+   * Sets locale-specific content overrides for a template. Each override must
+   * reference an element that already exists in the default content.
    *
    * @example
    * ```ts
@@ -231,7 +229,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Replace a notification template. All fields are required.
+   * Replaces a notification template in full, so send every field rather than only
+   * the ones you want changed. Publish separately to make it live.
    *
    * @example
    * ```ts
@@ -261,10 +260,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Retrieve the content of a notification template. The response shape depends on
-   * whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use
-   * the `version` query parameter to select draft, published, or a specific
-   * historical version.
+   * Returns a template's content and checksum. V2 templates return Elemental
+   * elements, while V1 templates return blocks and channels instead.
    *
    * @example
    * ```ts
diff --git a/src/resources/profiles/lists.ts b/src/resources/profiles/lists.ts
index bc21195..7824e70 100644
--- a/src/resources/profiles/lists.ts
+++ b/src/resources/profiles/lists.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Lists extends APIResource {
   /**
-   * Returns the subscribed lists for a specified user.
+   * Returns the lists a user is subscribed to, with paging. Use it to check what a
+   * recipient will receive before sending to a list.
    */
   retrieve(
     userID: string,
@@ -20,15 +21,16 @@ export class Lists extends APIResource {
   }
 
   /**
-   * Removes all list subscriptions for given user.
+   * Removes every list subscription for a user at once. Their profile and
+   * preferences are untouched, so this only affects list-targeted sends.
    */
   delete(userID: string, options?: RequestOptions): APIPromise<ListDeleteResponse> {
     return this._client.delete(path`/profiles/${userID}/lists`, options);
   }
 
   /**
-   * Subscribes the given user to one or more lists. If the list does not exist, it
-   * will be created.
+   * Subscribes a user to one or more lists, creating any list that does not yet
+   * exist. Optional preferences apply to each subscription.
    */
   subscribe(
     userID: string,
diff --git a/src/resources/profiles/profiles.ts b/src/resources/profiles/profiles.ts
index 358fae6..7a8c6c4 100644
--- a/src/resources/profiles/profiles.ts
+++ b/src/resources/profiles/profiles.ts
@@ -20,8 +20,8 @@ export class Profiles extends APIResource {
   lists: ListsAPI.Lists = new ListsAPI.Lists(this._client);
 
   /**
-   * Merge the supplied values with an existing profile or create a new profile if
-   * one doesn't already exist.
+   * Merges the supplied values into a user's profile, creating it if absent and
+   * leaving any key you omit untouched. Prefer this for everyday writes.
    */
   create(
     userID: string,
@@ -32,14 +32,16 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * Returns the specified user profile.
+   * Returns a user's stored profile and preferences, including the email address,
+   * phone number, and push tokens Courier can reach them on.
    */
   retrieve(userID: string, options?: RequestOptions): APIPromise<ProfileRetrieveResponse> {
     return this._client.get(path`/profiles/${userID}`, options);
   }
 
   /**
-   * Update a profile
+   * Applies a JSON Patch to a user profile, adding, removing, or replacing
+   * individual fields without sending the whole object.
    */
   update(userID: string, body: ProfileUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.patch(path`/profiles/${userID}`, {
@@ -50,7 +52,8 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * Deletes the specified user profile.
+   * Deletes a user's profile and stored contact details. List subscriptions and
+   * preferences are separate resources, so remove those too if required.
    */
   delete(userID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/profiles/${userID}`, {
@@ -60,11 +63,8 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * When using `PUT`, be sure to include all the key-value pairs required by the
-   * recipient's profile. Any key-value pairs that exist in the profile but fail to
-   * be included in the `PUT` request will be removed from the profile. Remember, a
-   * `PUT` update is a full replacement of the data. For partial updates, use the
-   * [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
+   * Overwrites a user profile in full, removing any key absent from the request
+   * body. Use the patch endpoint when changing a single field.
    */
   replace(
     userID: string,
diff --git a/src/resources/providers/catalog.ts b/src/resources/providers/catalog.ts
index b49b5b0..956f21d 100644
--- a/src/resources/providers/catalog.ts
+++ b/src/resources/providers/catalog.ts
@@ -8,10 +8,8 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Catalog extends APIResource {
   /**
-   * Returns the catalog of available provider types with their display names,
-   * descriptions, and configuration schema fields (snake_case, with `type` and
-   * `required`). Providers with no configurable schema return only `provider`,
-   * `name`, and `description`.
+   * Returns the provider types Courier supports, each with a display name,
+   * description, and the configuration fields it requires.
    */
   list(
     query: CatalogListParams | null | undefined = {},
diff --git a/src/resources/providers/providers.ts b/src/resources/providers/providers.ts
index 4c649aa..6719aed 100644
--- a/src/resources/providers/providers.ts
+++ b/src/resources/providers/providers.ts
@@ -13,34 +13,32 @@ export class Providers extends APIResource {
   catalog: CatalogAPI.Catalog = new CatalogAPI.Catalog(this._client);
 
   /**
-   * Create a new provider configuration. The `provider` field must be a known
-   * Courier provider key (see catalog).
+   * Configures a provider integration from a Courier provider key and its settings.
+   * Check the catalog endpoint for the schema each provider expects.
    */
   create(body: ProviderCreateParams, options?: RequestOptions): APIPromise<Provider> {
     return this._client.post('/providers', { body, ...options });
   }
 
   /**
-   * Fetch a single provider configuration by ID.
+   * Returns one configured provider by id, including its channel, provider key,
+   * alias, title, and current settings.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Provider> {
     return this._client.get(path`/providers/${id}`, options);
   }
 
   /**
-   * Replace an existing provider configuration. The `provider` key is required and
-   * determines which provider-specific settings schema is applied. All other fields
-   * are optional — omitted fields are cleared from the stored configuration (this is
-   * a full replacement, not a partial merge). Changing the provider type for an
-   * existing configuration is not supported.
+   * Replaces a provider's configuration in full, clearing any field you omit rather
+   * than merging it. Send the complete settings object.
    */
   update(id: string, body: ProviderUpdateParams, options?: RequestOptions): APIPromise<Provider> {
     return this._client.put(path`/providers/${id}`, { body, ...options });
   }
 
   /**
-   * List configured provider integrations for the current workspace. Supports
-   * cursor-based pagination.
+   * Lists the provider integrations configured in the workspace, one entry per
+   * channel and provider key with its alias and settings.
    */
   list(
     query: ProviderListParams | null | undefined = {},
@@ -50,8 +48,8 @@ export class Providers extends APIResource {
   }
 
   /**
-   * Delete a provider configuration. Returns 409 if the provider is still referenced
-   * by routing or notifications.
+   * Deletes a provider configuration, which fails while routing strategies or
+   * templates still reference it. Update those references first.
    */
   delete(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/providers/${id}`, {
diff --git a/src/resources/requests.ts b/src/resources/requests.ts
index 7c287ee..cdb8414 100644
--- a/src/resources/requests.ts
+++ b/src/resources/requests.ts
@@ -8,7 +8,8 @@ import { path } from '../internal/utils/path';
 
 export class Requests extends APIResource {
   /**
-   * Archive message
+   * Archives a send request by its request id. Use it to remove test sends or
+   * superseded requests from the message list without deleting them.
    */
   archive(requestID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/requests/${requestID}/archive`, {
diff --git a/src/resources/routing-strategies.ts b/src/resources/routing-strategies.ts
index 35593c3..ae9ce8d 100644
--- a/src/resources/routing-strategies.ts
+++ b/src/resources/routing-strategies.ts
@@ -35,8 +35,8 @@ export class RoutingStrategies extends APIResource {
   }
 
   /**
-   * Retrieve a routing strategy by ID. Returns the full entity including routing
-   * content and metadata.
+   * Returns one routing strategy by id with its name, tags, channels, and the
+   * routing rules that decide provider order and fallback.
    *
    * @example
    * ```ts
@@ -83,8 +83,8 @@ export class RoutingStrategies extends APIResource {
   }
 
   /**
-   * List notification templates associated with a routing strategy. Includes
-   * template metadata only, not full content.
+   * Returns the notification templates using a routing strategy, with paging. Check
+   * this before changing a strategy that templates depend on.
    *
    * @example
    * ```ts
diff --git a/src/resources/send.ts b/src/resources/send.ts
index bc35c9f..fe629e7 100644
--- a/src/resources/send.ts
+++ b/src/resources/send.ts
@@ -7,7 +7,8 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Send extends APIResource {
   /**
-   * Send a message to one or more recipients.
+   * Sends a message to one or more recipients and returns a requestId. Courier
+   * routes it to email, SMS, push, chat, or in-app based on your rules.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/preferences/items.ts b/src/resources/tenants/preferences/items.ts
index 5b93e99..f06e64c 100644
--- a/src/resources/tenants/preferences/items.ts
+++ b/src/resources/tenants/preferences/items.ts
@@ -9,7 +9,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Items extends APIResource {
   /**
-   * Create or Replace Default Preferences For Topic
+   * Sets a tenant's default opt-in status for one subscription topic, which applies
+   * to every member unless a user sets their own override.
    *
    * @example
    * ```ts
@@ -31,7 +32,8 @@ export class Items extends APIResource {
   }
 
   /**
-   * Remove Default Preferences For Topic
+   * Removes a tenant's default preference for one subscription topic, addressed by
+   * tenant id and topic id.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/templates/templates.ts b/src/resources/tenants/templates/templates.ts
index 262ca3d..7bd80dc 100644
--- a/src/resources/tenants/templates/templates.ts
+++ b/src/resources/tenants/templates/templates.ts
@@ -14,7 +14,8 @@ export class Templates extends APIResource {
   versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
 
   /**
-   * Get a Template in Tenant
+   * Returns a tenant's notification template with its content, version, and created,
+   * updated, and published timestamps.
    *
    * @example
    * ```ts
@@ -34,7 +35,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * List Templates in Tenant
+   * Lists a tenant's notification templates, each carrying its version and published
+   * timestamp. Paged.
    *
    * @example
    * ```ts
@@ -52,12 +54,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Deletes the tenant's notification template with the given `template_id`.
-   *
-   * Returns **204 No Content** with an empty body on success.
-   *
-   * Returns **404** if there is no template with this ID for the tenant, including a
-   * second `DELETE` after a successful removal.
+   * Deletes a tenant's notification template by id. Sends for that tenant then use
+   * the workspace template registered under the same id.
    *
    * @example
    * ```ts
@@ -75,10 +73,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Publishes a specific version of a notification template for a tenant.
-   *
-   * The template must already exist in the tenant's notification map. If no version
-   * is specified, defaults to publishing the "latest" version.
+   * Publishes a version of a tenant's notification template, making it the content
+   * that tenant's sends render from until you publish another.
    *
    * @example
    * ```ts
@@ -101,13 +97,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * Creates or updates a notification template for a tenant.
-   *
-   * If the template already exists for the tenant, it will be updated (200).
-   * Otherwise, a new template is created (201).
-   *
-   * Optionally publishes the template immediately if the `published` flag is set to
-   * true.
+   * Creates or updates a notification template scoped to one tenant, letting a
+   * tenant override the content the workspace template would send.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/templates/versions.ts b/src/resources/tenants/templates/versions.ts
index 62a07d6..326383f 100644
--- a/src/resources/tenants/templates/versions.ts
+++ b/src/resources/tenants/templates/versions.ts
@@ -8,13 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Versions extends APIResource {
   /**
-   * Fetches a specific version of a tenant template.
-   *
-   * Supports the following version formats:
-   *
-   * - `latest` - The most recent version of the template
-   * - `published` - The currently published version
-   * - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0")
+   * Returns one version of a tenant template, addressed by version number or by
+   * latest, with its content and publish timestamp.
    *
    * @example
    * ```ts
diff --git a/src/resources/tenants/tenants.ts b/src/resources/tenants/tenants.ts
index 1ac5e1f..70a3684 100644
--- a/src/resources/tenants/tenants.ts
+++ b/src/resources/tenants/tenants.ts
@@ -25,7 +25,8 @@ export class Tenants extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * Get a Tenant
+   * Returns one tenant with its name, parent tenant id, default preferences,
+   * properties, and the user profile applied to its members.
    *
    * @example
    * ```ts
@@ -37,7 +38,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Create or Replace a Tenant
+   * Creates or replaces a tenant from a name, parent, brand, properties, and default
+   * preferences supplied in the request body.
    *
    * @example
    * ```ts
@@ -51,7 +53,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Get a List of Tenants
+   * Lists the workspace's tenants, each carrying a name, parent tenant, properties,
+   * and default preferences. Paged.
    *
    * @example
    * ```ts
@@ -66,7 +69,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Delete a Tenant
+   * Deletes a tenant. Its members' workspace-level profiles and preferences live
+   * outside the tenant and are managed separately.
    *
    * @example
    * ```ts
@@ -81,7 +85,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Get Users in Tenant
+   * Returns the users belonging to a tenant with cursor paging. Use it to see who a
+   * tenant-scoped send will reach.
    *
    * @example
    * ```ts
diff --git a/src/resources/translations.ts b/src/resources/translations.ts
index ac89f26..db04387 100644
--- a/src/resources/translations.ts
+++ b/src/resources/translations.ts
@@ -8,7 +8,8 @@ import { path } from '../internal/utils/path';
 
 export class Translations extends APIResource {
   /**
-   * Get translations by locale
+   * Returns the translation strings stored for one domain and locale, for use in
+   * localized notification content.
    */
   retrieve(locale: string, params: TranslationRetrieveParams, options?: RequestOptions): APIPromise<string> {
     const { domain } = params;
@@ -16,7 +17,8 @@ export class Translations extends APIResource {
   }
 
   /**
-   * Update a translation
+   * Uploads the translation strings for one domain and locale. Courier uses them to
+   * render localized content for recipients in that locale.
    */
   update(locale: string, params: TranslationUpdateParams, options?: RequestOptions): APIPromise<void> {
     const { domain, body } = params;
diff --git a/src/resources/users/preferences.ts b/src/resources/users/preferences.ts
index b62fcee..ab2d9ef 100644
--- a/src/resources/users/preferences.ts
+++ b/src/resources/users/preferences.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Preferences extends APIResource {
   /**
-   * Fetch all user preferences.
+   * Returns a user's preference overrides with paging, one entry per subscription
+   * topic they have set a choice for.
    *
    * @example
    * ```ts
@@ -27,23 +28,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Replace a user's complete set of preference overrides in a single request. The
-   * topics in the request body become the recipient's entire set of overrides:
-   * listed topics are created or updated, and every existing override that is not
-   * included in the body is reset to its topic default. Submitting an empty `topics`
-   * array is a valid clear-all that resets every existing override.
-   *
-   * This operation is validation-atomic (all-or-nothing): structural validation
-   * fails fast with a single `400`, and if any topic is semantically invalid (an
-   * unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing
-   * request that is not available on the workspace's plan) the request returns a
-   * single `400` aggregating every failure in `errors` and writes nothing. On
-   * success it returns `200` with `items` (the complete resulting override set) and
-   * `deleted` (the ids of the overrides that were reset to default).
-   *
-   * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is
-   * returned in Courier's canonical topic id form, regardless of the form supplied
-   * in the request.
+   * Replaces a user's entire set of preference overrides. Any topic you leave out is
+   * reset to its default, so send the full set rather than a subset.
    *
    * @example
    * ```ts
@@ -72,23 +58,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Additively create or update a user's preferences for one or more subscription
-   * topics in a single request. Only the topics included in the request body are
-   * created or updated; any existing overrides for topics not listed are left
-   * untouched.
-   *
-   * Structural validation of the request body fails fast with a single `400`. Beyond
-   * that, each topic is processed independently (partial-success, not
-   * all-or-nothing): valid topics are written and returned in `items`, while topics
-   * that cannot be applied are collected in `errors` with a per-topic `reason` (for
-   * example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom
-   * routing request that is not available on the workspace's plan, or a write
-   * failure). The request therefore returns `200` with both lists whenever the body
-   * is structurally valid.
-   *
-   * Every `topic_id` in the response — in both `items` and `errors` — is returned in
-   * Courier's canonical topic id form, regardless of the form supplied in the
-   * request.
+   * Adds or updates a user's preferences for several subscription topics at once.
+   * Topics you leave out keep whatever they were set to before.
    *
    * @example
    * ```ts
@@ -121,9 +92,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Remove a user's preferences for a specific subscription topic, resetting the
-   * topic to its effective default. This operation is idempotent: deleting a
-   * preference that does not exist succeeds with no error.
+   * Removes a user's override for one subscription topic, resetting it to the
+   * effective default from the tenant or workspace.
    *
    * @example
    * ```ts
@@ -146,7 +116,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Fetch user preferences for a specific subscription topic.
+   * Returns a user's opt-in status and channel choices for one subscription topic,
+   * or the effective default if they have set no override.
    *
    * @example
    * ```ts
@@ -166,7 +137,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * Update or Create user preferences for a specific subscription topic.
+   * Sets a user's opt-in status and channel choices for one subscription topic,
+   * overriding the tenant default for that topic only.
    *
    * @example
    * ```ts
diff --git a/src/resources/users/tenants.ts b/src/resources/users/tenants.ts
index b68b7e0..ca30429 100644
--- a/src/resources/users/tenants.ts
+++ b/src/resources/users/tenants.ts
@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Tenants extends APIResource {
   /**
-   * Returns a paginated list of user tenant associations.
+   * Returns the tenants a user belongs to, with cursor paging. A user can belong to
+   * many tenants, each with its own profile and preferences.
    *
    * @example
    * ```ts
@@ -25,9 +26,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * This endpoint is used to add a user to multiple tenants in one call. A custom
-   * profile can also be supplied for each tenant. This profile will be merged with
-   * the user's main profile when sending to the user with that tenant.
+   * Adds a user to several tenants in one call, each optionally with a per-tenant
+   * profile that overrides their workspace profile.
    *
    * @example
    * ```ts
@@ -45,10 +45,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * This endpoint is used to add a single tenant.
-   *
-   * A custom profile can also be supplied with the tenant. This profile will be
-   * merged with the user's main profile when sending to the user with that tenant.
+   * Adds a user to one tenant, optionally with a tenant-specific profile that
+   * overrides their workspace profile for sends in that tenant.
    *
    * @example
    * ```ts
@@ -67,7 +65,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Removes a user from any tenants they may have been associated with.
+   * Removes a user from every tenant they belong to in one call. Their
+   * workspace-level profile is a separate resource.
    *
    * @example
    * ```ts
@@ -82,7 +81,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Removes a user from the supplied tenant.
+   * Removes a user from one tenant. Their other tenant memberships and workspace
+   * profile are managed through separate endpoints.
    *
    * @example
    * ```ts
diff --git a/src/resources/users/tokens.ts b/src/resources/users/tokens.ts
index 1e0c15f..68a6d19 100644
--- a/src/resources/users/tokens.ts
+++ b/src/resources/users/tokens.ts
@@ -8,7 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Tokens extends APIResource {
   /**
-   * Get single token available for a `:token`
+   * Returns one device token with its provider key, status and status reason, expiry
+   * date, and any properties stored alongside it.
    *
    * @example
    * ```ts
@@ -27,7 +28,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Apply a JSON Patch (RFC 6902) to the specified token.
+   * Applies a JSON Patch to a device token, changing its status, expiry, or
+   * properties without re-registering it.
    *
    * @example
    * ```ts
@@ -47,7 +49,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Gets all tokens available for a :user_id
+   * Returns every device token registered for a user, each with its provider key,
+   * status, and expiry date.
    *
    * @example
    * ```ts
@@ -59,7 +62,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Delete User Token
+   * Deletes one device token for a user, addressed by the token value, so push sends
+   * no longer target that device.
    *
    * @example
    * ```ts
@@ -77,7 +81,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Adds multiple tokens to a user and overwrites matching existing tokens.
+   * Registers several device tokens for a user in one call, overwriting any stored
+   * token with a matching value.
    *
    * @example
    * ```ts
@@ -92,7 +97,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Adds a single token to a user and overwrites a matching existing token.
+   * Registers one device token for a user against a provider key, overwriting the
+   * token if it already exists. Push sends resolve tokens per user.
    *
    * @example
    * ```ts
diff --git a/src/resources/workspace-preferences/topics.ts b/src/resources/workspace-preferences/topics.ts
index 420db23..de55f09 100644
--- a/src/resources/workspace-preferences/topics.ts
+++ b/src/resources/workspace-preferences/topics.ts
@@ -10,9 +10,8 @@ import { path } from '../../internal/utils/path';
 
 export class Topics extends APIResource {
   /**
-   * Create a subscription preference topic inside a workspace preference. Fails with
-   * 404 if the workspace preference does not exist. The topic id is generated and
-   * returned.
+   * Creates a subscription topic inside a workspace preference. The default status
+   * sets whether users start opted in, opted out, or required.
    *
    * @example
    * ```ts
@@ -32,9 +31,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * Retrieve a topic within a workspace preference. Returns 404 if the workspace
-   * preference does not exist, the topic does not exist, or the topic belongs to a
-   * different workspace preference.
+   * Returns one subscription topic with its default status, routing options, allowed
+   * preferences, and unsubscribe header setting.
    *
    * @example
    * ```ts
@@ -55,7 +53,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * List the topics in a workspace preference.
+   * Returns the subscription topics inside a workspace preference, each with its
+   * default status and routing options.
    *
    * @example
    * ```ts
@@ -73,8 +72,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * Archive a topic and remove it from its workspace preference. Same 404 rules as
-   * GET.
+   * Archives a subscription topic and removes it from its workspace preference,
+   * addressed by section id and topic id.
    *
    * @example
    * ```ts
diff --git a/src/resources/workspace-preferences/workspace-preferences.ts b/src/resources/workspace-preferences/workspace-preferences.ts
index e33e4f0..dc2c33f 100644
--- a/src/resources/workspace-preferences/workspace-preferences.ts
+++ b/src/resources/workspace-preferences/workspace-preferences.ts
@@ -19,9 +19,8 @@ export class WorkspacePreferences extends APIResource {
   topics: TopicsAPI.Topics = new TopicsAPI.Topics(this._client);
 
   /**
-   * Create a workspace preference. The workspace preference id is generated and
-   * returned. Topics are created inside a workspace preference via POST
-   * /preferences/sections/{section_id}/topics.
+   * Creates a workspace preference and returns its generated id. Add subscription
+   * topics to it afterwards with the topics endpoint.
    *
    * @example
    * ```ts
@@ -39,7 +38,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * Retrieve a workspace preference by id, including its topics.
+   * Returns one workspace preference by id, including its subscription topics,
+   * routing options, and custom routing flag.
    *
    * @example
    * ```ts
@@ -52,8 +52,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * List the workspace's preferences. Each workspace preference embeds its topics.
-   * Scoped to the workspace of the API key.
+   * Returns the workspace's preferences, each embedding its subscription topics,
+   * routing options, and whether custom routing is allowed.
    *
    * @example
    * ```ts
@@ -82,9 +82,8 @@ export class WorkspacePreferences extends APIResource {
   }
 
   /**
-   * Publish the workspace's preferences page. Takes a snapshot of every workspace
-   * preference with its topics under a new published version, making the current
-   * state visible on the hosted preferences page (non-draft).
+   * Publishes the workspace preference page, snapshotting every preference and
+   * topic, and returns the page id and a preview URL.
    *
    * @example
    * ```ts

From 7dfd9f4ba906534cb39b5a5905e723a7b073c7fc Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Sat, 25 Jul 2026 00:05:56 +0000
Subject: [PATCH 3/3] release: 7.21.1

---
 .release-please-manifest.json | 2 +-
 CHANGELOG.md                  | 9 +++++++++
 package.json                  | 2 +-
 src/version.ts                | 2 +-
 4 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 3107bf4..1e8c132 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "7.21.0"
+  ".": "7.21.1"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a38f1ca..08b03e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 7.21.1 (2026-07-25)
+
+Full Changelog: [v7.21.0...v7.21.1](https://github.com/trycourier/courier-node/compare/v7.21.0...v7.21.1)
+
+### Documentation
+
+* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-node/issues/172)) ([dba1cfc](https://github.com/trycourier/courier-node/commit/dba1cfc46d8dd557223158758a77ca3fd5a8a03d))
+* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-node/issues/174)) ([db95d94](https://github.com/trycourier/courier-node/commit/db95d94acdcfbf50bceb7282fc5cd393d539f7f9))
+
 ## 7.21.0 (2026-07-23)
 
 Full Changelog: [v7.20.0...v7.21.0](https://github.com/trycourier/courier-node/compare/v7.20.0...v7.21.0)
diff --git a/package.json b/package.json
index 607827f..748d340 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@trycourier/courier",
-  "version": "7.21.0",
+  "version": "7.21.1",
   "description": "The official TypeScript library for the Courier API",
   "author": "Courier <support@courier.com>",
   "types": "dist/index.d.ts",
diff --git a/src/version.ts b/src/version.ts
index 709152b..236ed92 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION = '7.21.0'; // x-release-please-version
+export const VERSION = '7.21.1'; // x-release-please-version