Skip to content

docs: custom reporting tags the Voice API - #421

Merged
wints merged 5 commits into
mainfrom
docs/custom-tags-voice-support
Aug 18, 2026
Merged

docs: custom reporting tags the Voice API#421
wints merged 5 commits into
mainfrom
docs/custom-tags-voice-support

Conversation

@wints

@wints wints commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Tagging a Voice session is confirmed working in production, but the docs still said custom tag data was supported for text translation only.

  • Rework the how-to guide: no longer limit to "translate requests" and add a section on tagging a Voice session, including that the header can only ride the session request (the WebSocket carries no headers), so a tag covers a whole session and cannot be changed mid-session or applied per utterance.
  • Add speech_to_text_minutes and speech_to_speech_minutes to CustomTagBreakdown, the analytics response examples, and the endpoint reference table, and note that voice minutes are not part of total_characters.
  • Document X-DeepL-Reporting-Tag in the spec as a reusable components.parameters entry, referenced from POST /v2/translate and POST /v3/voice/realtime. The header was previously absent from the spec entirely, including for text translation.
  • Add an August 18 release note and bump info.version to 3.13.0.

openapi.json is left untouched; CI regenerates it from the YAML.

Tagging a Voice session is confirmed working in production, but the docs
still said custom tag data was supported for text translation only.

- Rework the how-to guide: generalize the framing away from "translate
  requests" and add a section on tagging a Voice session, including that
  the header can only ride the session request (the WebSocket carries no
  headers), so a tag covers a whole session and cannot be changed
  mid-session or applied per utterance.
- Add speech_to_text_minutes and speech_to_speech_minutes to
  CustomTagBreakdown, the analytics response examples, and the endpoint
  reference table, and note that voice minutes are not part of
  total_characters.
- Document X-DeepL-Reporting-Tag in the spec as a reusable
  components.parameters entry, referenced from POST /v2/translate and
  POST /v3/voice/realtime. The header was previously absent from the
  spec entirely, including for text translation.
- Add an August 18 release note and bump info.version to 3.13.0.

openapi.json is left untouched; CI regenerates it from the YAML.
@mintlify

mintlify Bot commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
deepl-c950b784 🟢 Ready View Preview Aug 18, 2026, 7:59 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@wints wints changed the title docs: custom reporting tags work for the Voice API docs: custom reporting tags the Voice API Aug 18, 2026
@wints
wints requested review from aliasmac and seekuehe August 18, 2026 08:08
wints and others added 2 commits August 18, 2026 11:32
- Add the missing sample response to the Voice curl example, since
  CLAUDE.md requires request and response together and the translate
  section directly above it already shows one.
- Replace an em-dash (banned) and drop "utterances", which appears
  nowhere else in the docs, in favour of "audio chunks" as used
  throughout the Voice pages.
- Restore "only" in both scope warnings. Dropping it made the constraint
  read weaker than it is.
- Fix the total_characters description, in the reference table and in the
  spec, which still claimed all services while voice minutes now sit in
  the same breakdown and are excluded from that total.
- Note that the minute fields return fractional values.
- Lead the release note with what a custom tag is, per the changelog
  convention, so the entry stands alone.
- Trim the CustomReportingTag description down to purpose plus a link to
  the guide, in line with sibling parameters.
- Say "text translation" throughout rather than alternating with
  "translate", and cross-link the tag from the voice session flow and
  from the guide's own Limitations list.
Verified against production: a tagged session streamed 8800 ms, dropped
the WebSocket without ending the stream, reconnected via
GET /v3/voice/realtime with only the token (no tag header), then streamed
8754 ms more. All 17553 ms landed under the original tag across four
usage rows, with no untagged rows for the account.

This was the gap flagged in review. Reconnection is a normal flow and the
reconnect request cannot carry a tag, so silence here left developers
unable to tell whether reconnected audio kept its attribution.
@wints
wints merged commit bc5a4de into main Aug 18, 2026
3 checks passed
@wints
wints deleted the docs/custom-tags-voice-support branch August 18, 2026 12:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants