openapi: 3.0.3
info:
  title: IBM Watson Language Translator V3 Documents API
  description: 'REST API for translating text between 35+ languages, identifying the language of input text, listing available translation models, and creating or managing custom translation models. The base URL varies by region. IAM authentication via Bearer tokens is required. The API version parameter 2018-05-01 is required on all requests. NOTE: This service was deprecated in June 2023 and withdrawn in December 2024.'
  version: 3.0.0
  contact:
    name: IBM Watson
    url: https://cloud.ibm.com/apidocs/language-translator
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-deprecated: true
  x-deprecation-date: '2023-06-01'
  x-withdrawal-date: '2024-12-01'
servers:
- url: https://api.us-south.language-translator.watson.cloud.ibm.com
  description: US South
- url: https://api.us-east.language-translator.watson.cloud.ibm.com
  description: US East
- url: https://api.eu-de.language-translator.watson.cloud.ibm.com
  description: Frankfurt (EU)
- url: https://api.eu-gb.language-translator.watson.cloud.ibm.com
  description: London (EU)
- url: https://api.au-syd.language-translator.watson.cloud.ibm.com
  description: Sydney
- url: https://api.jp-tok.language-translator.watson.cloud.ibm.com
  description: Tokyo
- url: https://api.kr-seo.language-translator.watson.cloud.ibm.com
  description: Seoul
security:
- BearerAuth: []
tags:
- name: Documents
  description: Operations for translating documents
paths:
  /v3/documents:
    get:
      summary: List documents
      description: Lists documents that have been submitted for translation. Returns a list of documents with supporting meta data.
      operationId: listDocuments
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: Successful response with list of submitted documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Translate document
      description: Submit a document for translation. You can submit the document contents in the file parameter, and optionally the name of the document in the filename parameter. Specify the translation model to use for translation of the document contents by either providing a model ID using the model_id parameter or the source and target language code using the source and target parameters. IBM Watson Language Translator may reject documents submission requests if the file size limit is exceeded. The current size limit for document translation is 20 MB.
      operationId: translateDocument
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The contents of the source file to translate.
                filename:
                  type: string
                  description: The name of the input file in UTF-8 format, including the file extension. Used when providing a filename is needed.
                file_content_type:
                  type: string
                  description: The content type of the file.
                model_id:
                  type: string
                  description: The model to use for translation. model_id or both source and target is required.
                source:
                  type: string
                  description: Language code that specifies the language of the source document.
                target:
                  type: string
                  description: Language code that specifies the language for translation output.
                document_id:
                  type: string
                  description: To use a previously submitted document as the source for a new translation, enter the document_id of the document.
      responses:
        '202':
          description: Document accepted for translation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/documents/{document_id}:
    get:
      summary: Get document status
      description: Gets the translation status of a document. Returns the current status of a document translation. This method has to be invoked multiple times to determine when the translation has completed.
      operationId: getDocumentStatus
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/Version'
      - name: document_id
        in: path
        required: true
        description: The document ID of the document to retrieve status of.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with document translation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete document
      description: Deletes a document.
      operationId: deleteDocument
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/Version'
      - name: document_id
        in: path
        required: true
        description: Document ID of the document to delete.
        schema:
          type: string
      responses:
        '204':
          description: Document deleted successfully (no content returned)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/documents/{document_id}/translated_document:
    get:
      summary: Get translated document
      description: Gets the translated document associated with the given document ID. Returns the translated document in the same format as the original source file. You must check that the translation is complete before calling this method. You can use the Get document status method to check the translation status.
      operationId: getTranslatedDocument
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/Version'
      - name: document_id
        in: path
        required: true
        description: The document ID of the document that was submitted for translation.
        schema:
          type: string
      - name: Accept
        in: header
        description: The type of the response. Match the file type of the source file.
        schema:
          type: string
      responses:
        '200':
          description: Translated document binary response
          content:
            application/powerpoint:
              schema:
                type: string
                format: binary
            application/mspowerpoint:
              schema:
                type: string
                format: binary
            application/msword:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.presentationml.presentation:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
            application/vnd.ms-powerpoint:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
            text/html:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: Payload too large - file exceeds size limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Unsupported media type - file format not supported
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DocumentList:
      type: object
      description: DocumentList contains the list of documents with status.
      properties:
        documents:
          type: array
          description: An array of all previously submitted documents.
          items:
            $ref: '#/components/schemas/DocumentStatus'
    ErrorResponse:
      type: object
      description: Error response object.
      properties:
        code:
          type: integer
          description: HTTP status code.
          example: 400
        error:
          type: string
          description: Human-readable error description.
          example: Bad request
        description:
          type: string
          description: Detailed description of the error.
    DocumentStatus:
      type: object
      description: Information about the submitted document and the translation process.
      properties:
        document_id:
          type: string
          description: System generated ID identifying a document being translated using one specific translation model.
          example: abc123
        filename:
          type: string
          description: filename included in the request or extracted from the file name.
          example: report.docx
        status:
          type: string
          description: 'The status of the translation job associated with a submitted document. Valid values are: processing, available, failed, deleted.'
          enum:
          - processing
          - available
          - failed
          - deleted
          example: available
        model_id:
          type: string
          description: A globally unique string that identifies the underlying model that is used for translation.
          example: en-es
        base_model_id:
          type: string
          description: Model ID of the base model that was used to customize the model. If the model is not a custom model, this will be an empty string.
          example: en-es
        source:
          type: string
          description: Translation source language code.
          example: en
        detected_language_confidence:
          type: number
          format: double
          description: The confidence score for the source language identification. Returned only when the model used automatic language identification.
          minimum: 0
          maximum: 1
          example: 0.998
        target:
          type: string
          description: Translation target language code.
          example: es
        created:
          type: string
          format: date-time
          description: The time when the document was submitted.
        completed:
          type: string
          format: date-time
          description: The time when the translation completed (available or failed).
        word_count:
          type: integer
          description: The number of words in the source document.
          example: 523
        character_count:
          type: integer
          description: The number of characters in the source document, present only if available.
          example: 3142
  parameters:
    Version:
      name: version
      in: query
      required: true
      description: Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-05-01.
      schema:
        type: string
        example: '2018-05-01'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: IBM Cloud IAM token authentication
externalDocs:
  description: IBM Cloud API Docs - Language Translator
  url: https://cloud.ibm.com/apidocs/language-translator