release: 4.22.1#115
Open
stainless-app[bot] wants to merge 3 commits into
Open
Conversation
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>
Contributor
Author
|
🧪 Testing To try out this version of the SDK: Expires at: Mon, 24 Aug 2026 00:08:46 GMT |
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>
stainless-app
Bot
force-pushed
the
release-please--branches--main--changes--next
branch
from
July 25, 2026 00:05
e858c42 to
5bfa959
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated Release PR
4.22.1 (2026-07-25)
Full Changelog: v4.22.0...v4.22.1
Documentation
This pull request is managed by Stainless's GitHub App.
The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.
For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.
🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions