From 7adabe0badc4916784175d5c319c2cebea87aa1f Mon Sep 17 00:00:00 2001 From: Brianna Delgado Date: Tue, 10 Nov 2026 14:02:55 -0500 Subject: [PATCH 1/3] docs(openapi): align glossary, spoken terms, admin and paging details with API behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Glossaries: creating a glossary without dictionaries is allowed, and entries_format has no default; a dictionary without it returns 400 - Spoken terms: term_lists is optional on create, and PATCH accepts at most one term list - Admin API: document the key secret returned when creating a developer key, speech_to_speech_minutes in the usage breakdown, and the page_size parameter of the custom tag analytics endpoint - Paging: translation memories reduce page_size above 100 to 100 instead of rejecting it, and style rule lists reduce page_size above 10 to 10 Regenerated openapi.json from openapi.yaml. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 44 +++++++++++++++++++++++++++----------- api-reference/openapi.yaml | 35 ++++++++++++++++++++++-------- 2 files changed, 58 insertions(+), 21 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index f1029f70..4417b837 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -298,6 +298,18 @@ }, "example": "day" }, + { + "name": "page_size", + "in": "query", + "required": false, + "description": "The maximum number of usage items to return per page, between 1 and 1000. Values outside this range are rejected with a 400 error.", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 1000 + }, + "example": 100 + }, { "name": "page", "in": "query", @@ -5952,9 +5964,9 @@ "type": "integer", "default": 10, "minimum": 1, - "maximum": 25 + "maximum": 10 }, - "description": "The maximum number of style rule lists to return." + "description": "The maximum number of style rule lists to return. Values above 10 are reduced to 10." }, { "name": "detailed", @@ -7896,6 +7908,12 @@ "type": "boolean", "example": true }, + "secret": { + "description": "The API key secret, to use in the `Authorization` header. Returned only in the response to creating a key, and `null` in every other response. Store it when you create the key, because it can't be retrieved again.", + "type": "string", + "nullable": true, + "example": "0aa1b2c3-d4e5-f6a7-b8c9-d0e1f2a3b4c5:fx" + }, "usage_limits": { "description": "Usage limits for the API key.", "type": "object", @@ -9481,8 +9499,7 @@ "CreateMultilingualGlossaryParameters": { "type": "object", "required": [ - "name", - "dictionaries" + "name" ], "properties": { "name": { @@ -9491,7 +9508,7 @@ "example": "My Glossary" }, "dictionaries": { - "description": "Dictionaries to populate the glossary with.", + "description": "Dictionaries to populate the glossary with. Omit to create an empty glossary and add dictionaries later with `PUT /v3/glossaries/{glossary_id}/dictionaries`.", "type": "array", "items": { "$ref": "#/components/schemas/GlossaryDictionary" @@ -9793,14 +9810,13 @@ "example": "Hello\tGuten Tag" }, "GlossaryEntriesFormat": { - "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` (default) - tab-separated values\n- `csv` - comma-separated values\n\nSee [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format.", + "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` - tab-separated values\n- `csv` - comma-separated values\n\nRequired for every dictionary that includes `entries`. A dictionary without it is rejected with a 400 error.\n\nSee [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format.", "type": "string", "enum": [ "tsv", "csv" ], - "example": "tsv", - "default": "tsv" + "example": "tsv" }, "GlossaryEntryCount": { "description": "The number of entries in the glossary.", @@ -10108,8 +10124,7 @@ "CreateSpokenTermsParameters": { "type": "object", "required": [ - "name", - "term_lists" + "name" ], "properties": { "name": { @@ -10119,7 +10134,7 @@ "example": "Technical Terms" }, "term_lists": { - "description": "Array of term lists, one per language.", + "description": "Array of term lists, one per language. Omit to create an empty collection and add term lists later.", "type": "array", "items": { "$ref": "#/components/schemas/SpokenTermsListInput" @@ -10157,7 +10172,7 @@ "example": "Updated Technical Terms" }, "term_lists": { - "description": "Term lists to merge with existing lists.", + "description": "Term lists to merge with existing lists. Currently accepts at most one term list per request; sending more returns a 400 error.", "type": "array", "items": { "$ref": "#/components/schemas/SpokenTermsListInput" @@ -11344,6 +11359,11 @@ "type": "number", "description": "Duration of speech-to-text usage in minutes.", "example": 107.46 + }, + "speech_to_speech_minutes": { + "type": "number", + "description": "Duration of speech-to-speech usage in minutes.", + "example": 4.2 } } }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index c0dda760..287712a6 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -301,6 +301,15 @@ paths: - day default: period example: "day" + - name: page_size + in: query + required: false + description: The maximum number of usage items to return per page, between 1 and 1000. Values outside this range are rejected with a 400 error. + schema: + type: integer + minimum: 1 + maximum: 1000 + example: 100 - name: page in: query required: false @@ -4426,8 +4435,8 @@ paths: type: integer default: 10 minimum: 1 - maximum: 25 - description: The maximum number of style rule lists to return. + maximum: 10 + description: The maximum number of style rule lists to return. Values above 10 are reduced to 10. - name: detailed in: query schema: @@ -5736,6 +5745,11 @@ components: description: Flag indicating whether the API key is deactivated. The default value is `false`. type: boolean example: true + secret: + description: The API key secret, to use in the `Authorization` header. Returned only in the response to creating a key, and `null` in every other response. Store it when you create the key, because it can't be retrieved again. + type: string + nullable: true + example: 0aa1b2c3-d4e5-f6a7-b8c9-d0e1f2a3b4c5:fx usage_limits: description: Usage limits for the API key. type: object @@ -6992,14 +7006,13 @@ components: type: object required: - name - - dictionaries properties: name: description: Name to be associated with the glossary. type: string example: My Glossary dictionaries: - description: Dictionaries to populate the glossary with. + description: Dictionaries to populate the glossary with. Omit to create an empty glossary and add dictionaries later with `PUT /v3/glossaries/{glossary_id}/dictionaries`. type: array items: $ref: '#/components/schemas/GlossaryDictionary' @@ -7275,16 +7288,17 @@ components: GlossaryEntriesFormat: description: |- The format in which the glossary entries are provided. Formats currently available: - - `tsv` (default) - tab-separated values + - `tsv` - tab-separated values - `csv` - comma-separated values + Required for every dictionary that includes `entries`. A dictionary without it is rejected with a 400 error. + See [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format. type: string enum: - tsv - csv example: tsv - default: tsv GlossaryEntryCount: description: The number of entries in the glossary. type: integer @@ -7561,7 +7575,6 @@ components: type: object required: - name - - term_lists properties: name: description: Name for the Spoken Terms collection. @@ -7569,7 +7582,7 @@ components: maxLength: 1024 example: Technical Terms term_lists: - description: Array of term lists, one per language. + description: Array of term lists, one per language. Omit to create an empty collection and add term lists later. type: array items: $ref: '#/components/schemas/SpokenTermsListInput' @@ -7600,7 +7613,7 @@ components: maxLength: 1024 example: Updated Technical Terms term_lists: - description: Term lists to merge with existing lists. + description: Term lists to merge with existing lists. Currently accepts at most one term list per request; sending more returns a 400 error. type: array items: $ref: '#/components/schemas/SpokenTermsListInput' @@ -8765,6 +8778,10 @@ components: type: number description: Duration of speech-to-text usage in minutes. example: 107.46 + speech_to_speech_minutes: + type: number + description: Duration of speech-to-speech usage in minutes. + example: 4.2 KeyAndDayUsageItem: type: object description: Usage statistics for a specific API key and optionally a specific date. From 7f46b04de530d90487bc761378957ae51d305ac0 Mon Sep 17 00:00:00 2001 From: Brianna Delgado Date: Tue, 10 Nov 2026 15:51:57 -0500 Subject: [PATCH 2/3] docs(openapi): keep the style rules page_size maximum at 25 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 4 ++-- api-reference/openapi.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 4417b837..94a2af1f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -5964,9 +5964,9 @@ "type": "integer", "default": 10, "minimum": 1, - "maximum": 10 + "maximum": 25 }, - "description": "The maximum number of style rule lists to return. Values above 10 are reduced to 10." + "description": "The maximum number of style rule lists to return. Values above 25 are reduced to 25." }, { "name": "detailed", diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 287712a6..bff3ce9f 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4435,8 +4435,8 @@ paths: type: integer default: 10 minimum: 1 - maximum: 10 - description: The maximum number of style rule lists to return. Values above 10 are reduced to 10. + maximum: 25 + description: The maximum number of style rule lists to return. Values above 25 are reduced to 25. - name: detailed in: query schema: From 2e019539f8a7a6d38f27a6026f93e14df49b8e57 Mon Sep 17 00:00:00 2001 From: Brianna Delgado Date: Tue, 10 Nov 2026 15:56:35 -0500 Subject: [PATCH 3/3] docs(openapi): revert description edits on fields whose behavior isn't changing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 10 +++++----- api-reference/openapi.yaml | 10 ++++------ 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 94a2af1f..5499f151 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -5966,7 +5966,7 @@ "minimum": 1, "maximum": 25 }, - "description": "The maximum number of style rule lists to return. Values above 25 are reduced to 25." + "description": "The maximum number of style rule lists to return." }, { "name": "detailed", @@ -9508,7 +9508,7 @@ "example": "My Glossary" }, "dictionaries": { - "description": "Dictionaries to populate the glossary with. Omit to create an empty glossary and add dictionaries later with `PUT /v3/glossaries/{glossary_id}/dictionaries`.", + "description": "Dictionaries to populate the glossary with.", "type": "array", "items": { "$ref": "#/components/schemas/GlossaryDictionary" @@ -9810,7 +9810,7 @@ "example": "Hello\tGuten Tag" }, "GlossaryEntriesFormat": { - "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` - tab-separated values\n- `csv` - comma-separated values\n\nRequired for every dictionary that includes `entries`. A dictionary without it is rejected with a 400 error.\n\nSee [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format.", + "description": "The format in which the glossary entries are provided. Formats currently available:\n- `tsv` - tab-separated values\n- `csv` - comma-separated values\n\nSee [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format.", "type": "string", "enum": [ "tsv", @@ -10134,7 +10134,7 @@ "example": "Technical Terms" }, "term_lists": { - "description": "Array of term lists, one per language. Omit to create an empty collection and add term lists later.", + "description": "Array of term lists, one per language.", "type": "array", "items": { "$ref": "#/components/schemas/SpokenTermsListInput" @@ -10172,7 +10172,7 @@ "example": "Updated Technical Terms" }, "term_lists": { - "description": "Term lists to merge with existing lists. Currently accepts at most one term list per request; sending more returns a 400 error.", + "description": "Term lists to merge with existing lists.", "type": "array", "items": { "$ref": "#/components/schemas/SpokenTermsListInput" diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index bff3ce9f..726cef94 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4436,7 +4436,7 @@ paths: default: 10 minimum: 1 maximum: 25 - description: The maximum number of style rule lists to return. Values above 25 are reduced to 25. + description: The maximum number of style rule lists to return. - name: detailed in: query schema: @@ -7012,7 +7012,7 @@ components: type: string example: My Glossary dictionaries: - description: Dictionaries to populate the glossary with. Omit to create an empty glossary and add dictionaries later with `PUT /v3/glossaries/{glossary_id}/dictionaries`. + description: Dictionaries to populate the glossary with. type: array items: $ref: '#/components/schemas/GlossaryDictionary' @@ -7291,8 +7291,6 @@ components: - `tsv` - tab-separated values - `csv` - comma-separated values - Required for every dictionary that includes `entries`. A dictionary without it is rejected with a 400 error. - See [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format. type: string enum: @@ -7582,7 +7580,7 @@ components: maxLength: 1024 example: Technical Terms term_lists: - description: Array of term lists, one per language. Omit to create an empty collection and add term lists later. + description: Array of term lists, one per language. type: array items: $ref: '#/components/schemas/SpokenTermsListInput' @@ -7613,7 +7611,7 @@ components: maxLength: 1024 example: Updated Technical Terms term_lists: - description: Term lists to merge with existing lists. Currently accepts at most one term list per request; sending more returns a 400 error. + description: Term lists to merge with existing lists. type: array items: $ref: '#/components/schemas/SpokenTermsListInput'