docs(get-voices): sync sibling override description with base spec - #407
Merged
Merged
Conversation
The sibling SDK-generation override at fern/apis/waves/openapi/ get-voices-openapi-overrides.yaml was updated in #402 to match the base spec on the pool-scoped enum, but the description stopped short: the two markdown links (unified TTS route + get-all-models cross-link) were omitted from the override. The Waves spec drift CI check compares base vs sibling override, and this mismatch was failing every open PR that touched any waves spec file (#394, #401, #406, and any future spec edit). Copy the two link lines verbatim so the two files match token-for-token. Local run of scripts/spec-live-tests/spec_drift_check.py now reports PASS — no drift.
|
crim doesn't review pull requests automatically here. Comment |
abhishekmishragithub
pushed a commit
that referenced
this pull request
Sep 1, 2026
Rebased on top of current main. Delta vs main:
Atoms openapi.yaml corrections:
- DELETE /agent/{id}/archive: 'on' becomes required string enum
- Length caps added on campaign.name (40), audience.name (80),
knowledgebase.description (150), account.name (2-50)
- provider enum extended to [twilio, plivo, custom, whatsapp]
- POST /product/import-phone-number gains cpsLimit
- LLM enums extended with gpt-5.2-azure across four schema sites
- WorkflowType adds multi_agents (kept workflow_graph + single_prompt)
- Path-param regex + minLength on the two conversation endpoints
Waves API spec corrections:
- GET /waves/v1/{model}/get_voices: security: [] (endpoint is public,
live-verified with 200 without Authorization)
- GET /waves/v1/voice/get-all-models: auth optional (- {})
- POST /waves/v1/pulse/get_text: adds webhook_method, redact_pii,
redact_pci, numerals query params
- POST /waves/v1/voice-cloning: language field 22-value enum, drops
retired /waves/v1/lightning-large/add_voice reference from prose
- PCA + Waves analytics response schemas extended to match backend
Explicitly NOT included (from the original PR):
- callId path-param renames (callId->id, callId->conversationId):
path parameter names in OpenAPI are docs-only; the URL is identical
regardless. Rename would break SDK method arg names with no customer
benefit and force a semi-major release.
- generators.yml refs to openapi/generated/*.json and
asyncapi/generated/*.json: the JSON files don't exist yet, they
are produced by atoms-platform / waves-platform CI on merge-to-main.
Adding refs before the files exist would break fern generate.
Review comments addressed:
- Wasim (voice-cloning-openapi.yaml:10): dropped the retired
/waves/v1/lightning-large/add_voice reference from the description.
- Wasim (waves-v4/overrides/get-voices-openapi-overrides.yaml:15):
already resolved by #402/#407; nothing to do here.
- Hamees (pulse-stt-openapi.yaml:213): the redact_pii/redact_pci
descriptions cover the 'en + hi only' language constraint. The
redaction feature itself works on regular Pulse; the language
constraint is orthogonal to the pulse-pro question.
Changelog entry added. spec_drift_check.py -> PASS.
abhishekmishragithub
added a commit
that referenced
this pull request
Sep 1, 2026
* docs(atoms + waves): API-spec crosscheck against backend Zod validators
Rebased on top of current main. Delta vs main:
Atoms openapi.yaml corrections:
- DELETE /agent/{id}/archive: 'on' becomes required string enum
- Length caps added on campaign.name (40), audience.name (80),
knowledgebase.description (150), account.name (2-50)
- provider enum extended to [twilio, plivo, custom, whatsapp]
- POST /product/import-phone-number gains cpsLimit
- LLM enums extended with gpt-5.2-azure across four schema sites
- WorkflowType adds multi_agents (kept workflow_graph + single_prompt)
- Path-param regex + minLength on the two conversation endpoints
Waves API spec corrections:
- GET /waves/v1/{model}/get_voices: security: [] (endpoint is public,
live-verified with 200 without Authorization)
- GET /waves/v1/voice/get-all-models: auth optional (- {})
- POST /waves/v1/pulse/get_text: adds webhook_method, redact_pii,
redact_pci, numerals query params
- POST /waves/v1/voice-cloning: language field 22-value enum, drops
retired /waves/v1/lightning-large/add_voice reference from prose
- PCA + Waves analytics response schemas extended to match backend
Explicitly NOT included (from the original PR):
- callId path-param renames (callId->id, callId->conversationId):
path parameter names in OpenAPI are docs-only; the URL is identical
regardless. Rename would break SDK method arg names with no customer
benefit and force a semi-major release.
- generators.yml refs to openapi/generated/*.json and
asyncapi/generated/*.json: the JSON files don't exist yet, they
are produced by atoms-platform / waves-platform CI on merge-to-main.
Adding refs before the files exist would break fern generate.
Review comments addressed:
- Wasim (voice-cloning-openapi.yaml:10): dropped the retired
/waves/v1/lightning-large/add_voice reference from the description.
- Wasim (waves-v4/overrides/get-voices-openapi-overrides.yaml:15):
already resolved by #402/#407; nothing to do here.
- Hamees (pulse-stt-openapi.yaml:213): the redact_pii/redact_pci
descriptions cover the 'en + hi only' language constraint. The
redaction feature itself works on regular Pulse; the language
constraint is orthogonal to the pulse-pro question.
Changelog entry added. spec_drift_check.py -> PASS.
* docs(stt): drop 'Pulse Pro only' from async webhook description
The three webhook query params (webhook_url, webhook_method,
webhook_extra) and the async webhook mode bullet in the endpoint
overview said 'Pulse Pro only'. Async webhook mode is not restricted
to Pulse Pro; the wording was leaking a stale model constraint into
customer-facing docs. Drop the qualifier without replacement.
Response-field descriptions on processing_time_ms, rtfx, num_chunks,
and totalBytes are left intact for now; those genuinely differ per
model in the response envelope. Revisit if the pulse response starts
carrying them too.
* docs(get-voices): drop get-all-models fallback line from all three spec files
Removes the sentence 'To browse every voice across every model in one
call, use GET /waves/v1/voice/get-all-models instead.' from the
Get Voices endpoint description on the customer-facing API-ref page.
Kept the following sentence about the Lightning v3.1 + Lightning v3.1
Pro model cards for the canonical per-language voice list.
Removed in all three sync-locked files so spec_drift_check.py stays
green:
- fern/apis/waves-v4/overrides/get-voices-openapi-overrides.yaml
- fern/apis/waves/openapi/get-voices-openapi.yaml
- fern/apis/waves/openapi/get-voices-openapi-overrides.yaml
Local drift check PASS. llms.txt regenerated.
* docs(atoms): correct 'on' query on archive — live test says not required
Verification-loop finding: DELETE /agent/{id}/archive without any ?on=
query returns HTTP 200 with 'Agent archived' (or 409 'already archived').
The server accepts the request and defaults to on=true when the param
is omitted. Akshat's required: true claim did not match live behavior.
Revert to:
- required: false (server default kicks in when omitted)
- schema: string enum ['true', 'false'] with default 'true'
- description: '"true" (default) — archive the agent'.
Verified with 4 curl probes: ?on=true -> 200 archived; no param ->
409 (already archived, means default TRUE applied); ?on=false -> 200
unarchived; other values -> Zod reject.
* docs(atoms): cpsLimit max=50 + workflow_graph org-gating note
Two live-verified corrections rolled into one commit:
- cpsLimit on POST /product/import-phone-number: server rejects values
> 50 with 'CPS limit cannot exceed 50' and < 1 with 'CPS limit must
be at least 1'. Add maximum: 50 to the schema and quote both error
strings in the description so integrators see the exact bounds.
- WorkflowType.workflow_graph: live check on POST /agent with
workflowType=workflow_graph returns HTTP 403 'Conversational Flow
agents are no longer available for your organization.' The Zod enum
still lists the value, so keeping it in the enum is correct; the
gating happens at the authorization middleware, not the schema. Add
a Restricted note so integrators know a 403 does not mean the enum
value is wrong.
---------
Co-authored-by: abhishekmishragithub <abhishek@smallest.ai>
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
1 participant
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.
Summary
Post-#402 merge, the sibling SDK-generation override at `fern/apis/waves/openapi/get-voices-openapi-overrides.yaml` had its enum updated to match the base spec but its description stopped short: the two markdown links (unified TTS route + `get-all-models` cross-link) were omitted from the override.
The `Waves spec drift` CI check compares base vs sibling override and this mismatch was failing every open PR that touched any Waves spec file (#394, #401, #406, plus any new spec edit).
Fix
Copy the two link lines verbatim so the two files match token-for-token.
Test plan