trycourier · stainless-app · Jul 23, 2026 · Jul 25, 2026 · Jul 25, 2026
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "4.22.0"
+  ".": "4.22.1"
 }
diff --git 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-5c878919b3df530781ebcd4ab1cda83606304da75c53fe0817d4c725d5bbbe73.yml
+openapi_spec_hash: dd37022222543ff064200e65e4b82f59
 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 4.22.1 (2026-07-25)
+
+Full Changelog: [v4.22.0...v4.22.1](https://github.com/trycourier/courier-java/compare/v4.22.0...v4.22.1)
+
+### Documentation
+
+* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-java/issues/172)) ([1d09244](https://github.com/trycourier/courier-java/commit/1d09244b56cb1ed9c98e28365d7509cd9dbe0018))
+* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-java/issues/174)) ([3453be3](https://github.com/trycourier/courier-java/commit/3453be34b9c9713b88aa72e64c6fdfa3251a2fae))
+
 ## 4.22.0 (2026-07-23)
 
 Full Changelog: [v4.21.0...v4.22.0](https://github.com/trycourier/courier-java/compare/v4.21.0...v4.22.0)

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.courier"
-    version = "4.22.0" // x-release-please-version
+    version = "4.22.1" // x-release-please-version
 }
 
 subprojects {

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt
@@ -11,7 +11,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AudienceDeleteParams
 private constructor(
     private val audienceId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AudienceListMembersParams
 private constructor(
     private val audienceId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AudienceListParams
 private constructor(
     private val cursor: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AudienceRetrieveParams
 private constructor(
     private val audienceId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt
@@ -21,7 +21,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Creates or updates audience. */
+/**
+ * Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates
+ * automatically as profiles change.
+ */
 class AudienceUpdateParams
 private constructor(
     private val audienceId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AuditEventListParams
 private constructor(
     private val cursor: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AuditEventRetrieveParams
 private constructor(
     private val auditEventId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt
@@ -18,7 +18,10 @@ import com.fasterxml.jackson.annotation.JsonProperty
 import java.util.Collections
 import java.util.Objects
 
-/** 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.
+ */
 class AuthIssueTokenParams
 private constructor(
     private val body: Body,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt
@@ -13,7 +13,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class AutomationListParams
 private constructor(
     private val cursor: String?,

diff --git a/...ava-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt b/...ava-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt
@@ -35,9 +35,7 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class InvokeInvokeAdHocParams
 private constructor(

diff --git a/...ore/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt b/...ore/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt
@@ -21,7 +21,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class InvokeInvokeByTemplateParams
 private constructor(
     private val templateId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt
@@ -21,8 +21,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class BrandCreateParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt
@@ -11,7 +11,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class BrandDeleteParams
 private constructor(
     private val brandId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get the list of brands. */
+/**
+ * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and
+ * published version.
+ */
 class BrandListParams
 private constructor(
     private val cursor: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Fetch a specific brand by brand ID. */
+/**
+ * Returns one brand by id, including its colors, logo and styling settings, Handlebars snippets,
+ * and published version.
+ */
 class BrandRetrieveParams
 private constructor(
     private val brandId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt
@@ -20,7 +20,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class BrandUpdateParams
 private constructor(
     private val brandId: String?,

diff --git a/...-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt b/...-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt
@@ -10,9 +10,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class ScheduleListInstancesParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt
@@ -22,7 +22,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class InboundTrackEventParams
 private constructor(
     private val body: Body,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt
@@ -12,8 +12,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class JourneyArchiveParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt
@@ -9,11 +9,8 @@ import com.courier.core.http.QueryParams
 import java.util.Objects
 
 /**
- * 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.
  */
 class JourneyCancelParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt
@@ -10,11 +10,8 @@ import com.courier.core.http.QueryParams
 import java.util.Objects
 
 /**
- * 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.
  */
 class JourneyCreateParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt
@@ -12,8 +12,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class JourneyInvokeParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt
@@ -13,7 +13,9 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get the list of journeys. */
+/**
+ * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor.
+ */
 class JourneyListParams
 private constructor(
     private val cursor: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt
@@ -9,7 +9,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class JourneyListVersionsParams
 private constructor(
     private val templateId: String?,

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt
@@ -12,8 +12,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class JourneyPublishParams
 private constructor(

diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt
@@ -12,10 +12,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class JourneyReplaceParams
 private constructor(

diff --git a/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt b/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt
@@ -12,7 +12,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class TemplateArchiveParams
 private constructor(
     private val templateId: String,

diff --git a/...-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt b/...-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt
@@ -11,7 +11,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class TemplateListVersionsParams
 private constructor(

diff --git a/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt b/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt
@@ -14,8 +14,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * 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.
  */
 class TemplatePublishParams
 private constructor(

diff --git a/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt b/...-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt
@@ -12,7 +12,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** 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.
+ */
 class TemplateReplaceParams
 private constructor(
     private val templateId: String,