From 918a9a9d4dc8249df789250410a19d5a4675f053 Mon Sep 17 00:00:00 2001 From: Thomas Neil Date: Thu, 10 Sep 2026 09:45:10 +0200 Subject: [PATCH] docs: align Quality Evaluation API with the current contract Pluralize /v1/quality-evaluations, drop poll summary/score, echo source/target/entries, and keep the pages hidden in nav. --- api-reference/openapi.json | 125 +++++++++++--------- api-reference/openapi.yaml | 89 +++++++------- api-reference/quality-evaluation.mdx | 4 +- api-reference/quality-evaluation/poll.mdx | 9 +- api-reference/quality-evaluation/submit.mdx | 2 +- docs.json | 9 ++ 6 files changed, 132 insertions(+), 106 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 72e5e2cc..ef7fe8a5 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -6479,7 +6479,7 @@ } } }, - "/v1/quality-evaluation": { + "/v1/quality-evaluations": { "post": { "tags": [ "QualityEvaluation" @@ -6532,7 +6532,7 @@ }, "example": { "job_id": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19", - "poll_url": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "poll_url": "/v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" } } } @@ -6574,7 +6574,7 @@ ] } }, - "/v1/quality-evaluation/{job_id}": { + "/v1/quality-evaluations/{job_id}": { "get": { "tags": [ "QualityEvaluation" @@ -6587,7 +6587,7 @@ "name": "job_id", "in": "path", "required": true, - "description": "The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID.", + "description": "The job identifier returned by `POST /v1/quality-evaluations`. Must be a valid UUID.", "schema": { "type": "string", "format": "uuid", @@ -6635,7 +6635,9 @@ } ] } - ] + ], + "source": "Our Q3 revenue came in 5% above forecast.", + "target": "Unser Q3-Umsatz lag 5 % unter der Prognose." }, { "segment_index": 1, @@ -6671,23 +6673,11 @@ } ] } - ] - } - ], - "summary": { - "overall_score": 72, - "granular_counts": { - "Accuracy": { - "Mistranslation": { - "Critical": 1, - "Minor": 1 - }, - "Omission": { - "Major": 1 - } - } + ], + "source": "Please share these results with your teams by Friday.", + "target": "Bitte teilen Sie diese Ergebnisse mit Ihrem Team." } - } + ] } } } @@ -10841,6 +10831,16 @@ "type": "string", "description": "Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs).", "example": "de" + }, + "glossary_ids": { + "type": "array", + "description": "Optional glossary IDs to include when evaluating the segments. Empty values are rejected.", + "items": { + "type": "string" + }, + "example": [ + "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + ] } } }, @@ -10883,13 +10883,13 @@ "job_id": { "type": "string", "format": "uuid", - "description": "The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result.", + "description": "The job identifier. Use it with `GET /v1/quality-evaluations/{job_id}` to poll for the result.", "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" }, "poll_url": { "type": "string", "description": "Relative URL you can use to poll for the result.", - "example": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "example": "/v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" } } }, @@ -10920,8 +10920,7 @@ "required": [ "job_id", "status", - "segments", - "summary" + "segments" ], "properties": { "job_id": { @@ -10942,39 +10941,6 @@ "items": { "$ref": "#/components/schemas/QualityEvaluationSegment" } - }, - "summary": { - "type": "object", - "required": [ - "overall_score", - "granular_counts" - ], - "description": "Aggregate quality results across all segments.", - "properties": { - "overall_score": { - "type": "integer", - "minimum": 0, - "maximum": 100, - "description": "Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary).", - "example": 72 - }, - "granular_counts": { - "type": "object", - "description": "Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts.", - "additionalProperties": true, - "example": { - "Accuracy": { - "Mistranslation": { - "Critical": 1, - "Minor": 1 - }, - "Omission": { - "Major": 1 - } - } - } - } - } } } }, @@ -11032,6 +10998,23 @@ "description": "Zero-based index matching the position of this segment in the request.", "example": 0 }, + "source": { + "type": "string", + "description": "Source text echoed from the evaluation pipeline. Omitted when empty.", + "example": "Our Q3 revenue came in 5% above forecast." + }, + "target": { + "type": "string", + "description": "Target text echoed from the evaluation pipeline. Omitted when empty.", + "example": "Unser Q3-Umsatz lag 5 % unter der Prognose." + }, + "entries": { + "type": "array", + "description": "Glossary matches applied to this segment. Omitted when there are no matches.", + "items": { + "$ref": "#/components/schemas/QualityEvaluationGlossaryEntry" + } + }, "errors": { "type": "array", "description": "Quality issues identified in this segment. Empty if no issues were found.", @@ -11041,6 +11024,32 @@ } } }, + "QualityEvaluationGlossaryEntry": { + "type": "object", + "required": [ + "source_entry", + "target_entry" + ], + "properties": { + "source_entry": { + "type": "string", + "description": "Glossary source term.", + "example": "revenue" + }, + "target_entry": { + "type": "string", + "description": "Glossary target term.", + "example": "Umsatz" + }, + "ranges": { + "type": "array", + "description": "Half-open `[start, end)` spans on the segment target text where this match applies.", + "items": { + "$ref": "#/components/schemas/QualityEvaluationSpan" + } + } + } + }, "QualityEvaluationIssue": { "type": "object", "required": [ diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 8fe39562..5603f0ef 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4508,7 +4508,7 @@ paths: $ref: '#/components/responses/NotFound' "429": $ref: '#/components/responses/TooManyRequests' - /v1/quality-evaluation: + /v1/quality-evaluations: post: tags: - QualityEvaluation @@ -4546,7 +4546,7 @@ paths: $ref: '#/components/schemas/QualityEvaluationJobCreated' example: job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 - poll_url: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + poll_url: /v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 400: description: |- Request validation failed. Common causes: @@ -4575,7 +4575,7 @@ paths: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] - /v1/quality-evaluation/{job_id}: + /v1/quality-evaluations/{job_id}: get: tags: - QualityEvaluation @@ -4587,7 +4587,7 @@ paths: - name: job_id in: path required: true - description: The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID. + description: The job identifier returned by `POST /v1/quality-evaluations`. Must be a valid UUID. schema: type: string format: uuid @@ -4607,6 +4607,8 @@ paths: status: done segments: - segment_index: 0 + source: Our Q3 revenue came in 5% above forecast. + target: Unser Q3-Umsatz lag 5 % unter der Prognose. errors: - type: Accuracy sub_type: Mistranslation @@ -4619,6 +4621,8 @@ paths: - start: 20 end: 29 - segment_index: 1 + source: Please share these results with your teams by Friday. + target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. errors: - type: Accuracy sub_type: Omission @@ -4638,15 +4642,6 @@ paths: target_spans: - start: 38 end: 48 - summary: - overall_score: 72 - granular_counts: - Accuracy: - Mistranslation: - Critical: 1 - Minor: 1 - Omission: - Major: 1 202: description: Job is still processing. Continue polling after the time suggested by the `Retry-After` header. headers: @@ -8127,6 +8122,13 @@ components: type: string description: Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs). example: de + glossary_ids: + type: array + description: Optional glossary IDs to include when evaluating the segments. Empty values are rejected. + items: + type: string + example: + - "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" segments: type: array minItems: 1 @@ -8157,12 +8159,12 @@ components: job_id: type: string format: uuid - description: The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result. + description: The job identifier. Use it with `GET /v1/quality-evaluations/{job_id}` to poll for the result. example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 poll_url: type: string description: Relative URL you can use to poll for the result. - example: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + example: /v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 QualityEvaluationProcessing: type: object required: @@ -8185,7 +8187,6 @@ components: - job_id - status - segments - - summary properties: job_id: type: string @@ -8201,30 +8202,6 @@ components: description: One entry per submitted segment, in request order. items: $ref: '#/components/schemas/QualityEvaluationSegment' - summary: - type: object - required: - - overall_score - - granular_counts - description: Aggregate quality results across all segments. - properties: - overall_score: - type: integer - minimum: 0 - maximum: 100 - description: Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary). - example: 72 - granular_counts: - type: object - description: Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts. - additionalProperties: true - example: - Accuracy: - Mistranslation: - Critical: 1 - Minor: 1 - Omission: - Major: 1 QualityEvaluationFailed: title: Error type: object @@ -8266,11 +8243,43 @@ components: type: integer description: Zero-based index matching the position of this segment in the request. example: 0 + source: + type: string + description: Source text echoed from the evaluation pipeline. Omitted when empty. + example: Our Q3 revenue came in 5% above forecast. + target: + type: string + description: Target text echoed from the evaluation pipeline. Omitted when empty. + example: Unser Q3-Umsatz lag 5 % unter der Prognose. + entries: + type: array + description: Glossary matches applied to this segment. Omitted when there are no matches. + items: + $ref: '#/components/schemas/QualityEvaluationGlossaryEntry' errors: type: array description: Quality issues identified in this segment. Empty if no issues were found. items: $ref: '#/components/schemas/QualityEvaluationIssue' + QualityEvaluationGlossaryEntry: + type: object + required: + - source_entry + - target_entry + properties: + source_entry: + type: string + description: Glossary source term. + example: revenue + target_entry: + type: string + description: Glossary target term. + example: Umsatz + ranges: + type: array + description: Half-open `[start, end)` spans on the segment target text where this match applies. + items: + $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationIssue: type: object required: diff --git a/api-reference/quality-evaluation.mdx b/api-reference/quality-evaluation.mdx index 616be8ca..8ae38fb8 100644 --- a/api-reference/quality-evaluation.mdx +++ b/api-reference/quality-evaluation.mdx @@ -25,8 +25,8 @@ Identify quality issues with your translations through a two-step process: | **Endpoint** | **Limit** | |---|---| -| `POST /v1/quality-evaluation` | 100 requests per minute per API key | -| `GET /v1/quality-evaluation/{job_id}` | 1,000 requests per minute per API key | +| `POST /v1/quality-evaluations` | 100 requests per minute per API key | +| `GET /v1/quality-evaluations/{job_id}` | 1,000 requests per minute per API key | Exceeding either limit returns `429 Too Many Requests`. diff --git a/api-reference/quality-evaluation/poll.mdx b/api-reference/quality-evaluation/poll.mdx index 50b2f8e7..4a40f18b 100644 --- a/api-reference/quality-evaluation/poll.mdx +++ b/api-reference/quality-evaluation/poll.mdx @@ -1,16 +1,15 @@ --- -openapi: get /v1/quality-evaluation/{job_id} +openapi: get /v1/quality-evaluations/{job_id} title: "Poll for the evaluation result" --- See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits. -### Summary +### Echoed segment text -The `summary` object aggregates the results across all segments: +A `done` response echoes each segment's `source` and `target` from the evaluation pipeline. -* `overall_score` rates the overall translation quality from 0 (lowest) to 100 (highest). The score is based on the severity of detected issues and adjusts for the length of the text, so a single issue has less impact on a longer translation than on a shorter one. -* `granular_counts` breaks down the number of issues, nested by `type`, then `sub_type`, then `severity`. +`entries` lists glossary matches applied to that segment (`source_entry`, `target_entry`, and `ranges`). The field is omitted when there are no matches. ### Severity values diff --git a/api-reference/quality-evaluation/submit.mdx b/api-reference/quality-evaluation/submit.mdx index 2aa6349e..535e8e9c 100644 --- a/api-reference/quality-evaluation/submit.mdx +++ b/api-reference/quality-evaluation/submit.mdx @@ -1,5 +1,5 @@ --- -openapi: post /v1/quality-evaluation +openapi: post /v1/quality-evaluations title: "Submit an evaluation job" --- diff --git a/docs.json b/docs.json index 38559381..21130fa2 100644 --- a/docs.json +++ b/docs.json @@ -333,6 +333,15 @@ "api-reference/jobs-voice-translate/reference" ] }, + { + "group": "Quality Evaluation", + "hidden": true, + "pages": [ + "api-reference/quality-evaluation", + "api-reference/quality-evaluation/submit", + "api-reference/quality-evaluation/poll" + ] + }, { "group": "Languages", "pages": [