openapi: 3.0.3
info:
  title: LILT Create Documents API
  description: "LILT API Support: https://lilt.atlassian.net/servicedesk/customer/portals\n\nThe LILT API enables programmatic access to the full-range of LILT backend services including:\n  * Training of and translating with interactive, adaptive machine translation\n  * Large-scale translation memory\n  * The Lexicon (a large-scale termbase)\n  * Programmatic control of the LILT CAT environment\n  * Translation memory synchronization\n\n\nRequests and responses are in JSON format. The REST API only responds to HTTPS / SSL requests.\n\nThe base url for this REST API is `https://api.lilt.com/`.\n\n## Authentication\n\nRequests are authenticated via API key, which requires the Business plan.\n\nRequests are authenticated using [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Add your API key as both the `username` and `password`.\n\nFor development, you may also pass the API key via the `key` query parameter. This is less secure than HTTP Basic Auth, and is not recommended for production use.\n\n## Quotas\n\nOur services have a general quota of 4000 requests per minute. Should you hit the maximum requests per minute, you will need to wait 60 seconds before you can send another request.\n"
  version: v3.0.3
  license:
    name: LILT Platform Terms and Conditions
    url: https://lilt.com/lilt-platform-terms-and-conditions
servers:
- url: https://api.lilt.com
security:
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Documents
paths:
  /v2/documents/files:
    get:
      tags:
      - Documents
      summary: Download a Document
      description: "Export a Document that has been translated in the Lilt web application.\nAny Document can be downloaded in XLIFF 1.2 format, or can be retrieved in its original uploaded format by setting `is_xliff=false`.\nThis endpoint will fail if either (a) export or (b) pre-translation operations are in-progress. The status of those operations can be determined by retrieving the Document resource.\nExample CURL command:\n```bash\n  curl -X GET https://api.lilt.com/v2/documents/files?key=API_KEY&id=274 -o from_lilt.xliff\n```\n\n"
      operationId: downloadDocument
      parameters:
      - name: id
        in: query
        description: An unique Document identifier.
        required: true
        schema:
          type: integer
      - name: is_xliff
        in: query
        description: Download the document in XLIFF 1.2 format.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: A file.
          content:
            application/octet-stream:
              schema:
                title: DocumentDownloadResponse
                type: string
                format: byte
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '502':
          description: File in pretranslation.
          content: {}
        default:
          description: Unexpected error
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Documents
      summary: Upload a File
      description: "Create a Document from a file in any of the formats [documented in our knowledge base](/kb/supported-file-formats).\nRequest parameters should be passed as JSON object with the header field `LILT-API`.\n\nFile names in the header can only contain [US-ASCII characters](https://en.wikipedia.org/wiki/ASCII). File names with characters outside of US-ASCII should be [URI encoded](https://en.wikipedia.org/wiki/Percent-encoding) or transliterated to US-ASCII strings.\n\nExample CURL command:\n```bash\n  curl -X POST https://api.lilt.com/v2/documents/files?key=API_KEY \\\n  --header \"LILT-API: {\\\"name\\\": \\\"introduction.xliff\\\",\\\"pretranslate\\\": \\\"tm+mt\\\",\\\"project_id\\\": 9}\" \\\n  --header \"Content-Type: application/octet-stream\" \\\n  --data-binary @Introduction.xliff\n```\n\n"
      operationId: uploadDocument
      parameters:
      - name: name
        in: header
        description: A file name.
        required: true
        schema:
          type: string
      - name: project_id
        in: header
        description: A unique Project identifier.
        required: true
        schema:
          type: integer
      - name: pretranslate
        in: header
        description: 'An optional parameter indicating if and how the document will be

          pretranslated upon being uploaded.

          The accepted values are `TM`, or `TM+MT`

          '
        schema:
          type: string
      - name: auto_accept
        in: header
        description: 'An optional parameter to auto-accept segments with 100% translation

          memory matches when the `pretranslate` option is also set, or to

          auto-accept any target data that is present when the uploaded file

          is XLIFF. If omitted it will default to your organization settings for `Accept and lock exact matches`,

          if set to `false`, no segments will be auto-accepted.

          '
        schema:
          type: boolean
      - name: case_sensitive
        in: header
        description: 'An optional parameter to use case sensitive translation memory matching when the `pretranslate`

          option is also enabled. Matches must have identical character-by-character case to qualify as matches.

          Default value matches your organization settings for `Use case sensitive translation memory matching` setting

          '
        schema:
          type: boolean
      - name: match_attribution
        in: header
        description: 'An optional parameter to attribute translation authorship of exact matches to the author of the file

          when the `pretranslate` option is also enabled. Default value matches your organization settings for `Translation authorship` setting

          '
        schema:
          type: boolean
      - name: config_id
        in: header
        description: 'An optional pararameter to specify an import configuration to

          be applied when extracting translatable content from this file.

          '
        schema:
          type: integer
      requestBody:
        description: 'The file contents to be uploaded. The entire POST body will be

          treated as the file.

          '
        content:
          application/octet-stream:
            schema:
              title: DocumentUploadBody
              type: string
              format: binary
              example: '<?xml version="1.0" encoding="UTF-8" standalone="no"?>

                <xliff xmlns="urn:oasis:names:tc:xliff:document:1.2">

                ...

                </xliff>'
        required: true
      responses:
        '200':
          description: A Document object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentWithSegments'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /v2/documents/pretranslate:
    post:
      tags:
      - Documents
      summary: Pretranslate Documents
      description: 'Pretranslate one or more Documents using translation memory (TM) and,

        optionally, machine translation (MT). Only documents that are not

        currently importing/exporting and are not already pretranslating will

        be pretranslated; the response always reflects the current state of

        every requested Document id, whether or not it was eligible.


        This is an asynchronous operation. The endpoint returns immediately

        with a `202` response once pretranslation has been queued; poll the

        Document resource (or the `is_pretranslating` / `status.pretranslation`

        fields it returns) to see when pretranslation has finished.


        This endpoint is subject to a per-organization rate limit. See the

        [API Rate Limits guide](/developers/guides/rate-limits) for details on

        how to read `429` responses and batch requests efficiently by passing

        multiple document ids in a single call.


        Example CURL:

        ```bash

        curl -X POST ''https://api.lilt.com/v2/documents/pretranslate?key=API_KEY'' \

        --header ''Content-Type: application/json'' \

        --data-raw ''{"id": [274, 275], "mode": "TM+MT", "auto_accept": true}''

        ```


        '
      operationId: pretranslateDocuments
      parameters:
      - name: auto_accept
        in: query
        description: Auto-accept segments with 100% translation memory matches. Can also be passed in the request body. Defaults to your organization's `Accept and lock exact matches` setting.
        schema:
          type: boolean
      - name: case_sensitive
        in: query
        description: Use case-sensitive translation memory matching. Can also be passed in the request body. Defaults to your organization's `Use case sensitive translation memory matching` setting.
        schema:
          type: boolean
      - name: attribute_to_creator
        in: query
        description: Attribute translation authorship of exact matches to the author of the document. Can also be passed in the request body. Defaults to your organization's `Translation authorship` setting.
        schema:
          type: boolean
      - name: mode
        in: query
        description: Pretranslation mode. Can also be passed in the request body. Defaults to `TM`.
        schema:
          type: string
          enum:
          - TM
          - TM+MT
          default: TM
      requestBody:
        description: The Document id(s) to pretranslate, plus optional pretranslation options.
        content:
          application/json:
            schema:
              title: PretranslateDocumentsBody
              type: object
              required:
              - id
              properties:
                id:
                  description: A Document id, or an array of Document ids, to pretranslate.
                  oneOf:
                  - type: integer
                  - type: array
                    items:
                      type: integer
                  example:
                  - 274
                  - 275
                mode:
                  type: string
                  description: Pretranslation mode. Defaults to `TM`.
                  enum:
                  - TM
                  - TM+MT
                  default: TM
                auto_accept:
                  type: boolean
                  description: Auto-accept segments with 100% translation memory matches. Defaults to your organization's `Accept and lock exact matches` setting.
                case_sensitive:
                  type: boolean
                  description: Use case-sensitive translation memory matching. Defaults to your organization's `Use case sensitive translation memory matching` setting.
                attribute_to_creator:
                  type: boolean
                  description: Attribute translation authorship of exact matches to the author of the document. Defaults to your organization's `Translation authorship` setting.
        required: true
      responses:
        '202':
          description: Pretranslation has been queued. Returns the current state of every requested Document.
          content:
            application/json:
              schema:
                title: PretranslateDocumentsResponse
                type: object
                properties:
                  id:
                    type: array
                    description: The Document ids that were requested.
                    items:
                      type: integer
                    example:
                    - 274
                    - 275
                  is_pretranslating:
                    type: boolean
                    description: Always `true` for a successfully queued request.
                    example: true
                  documents:
                    type: array
                    description: The current state of each requested Document.
                    items:
                      $ref: '#/components/schemas/DocumentWithoutSegments'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          description: Rate limit exceeded. See the [API Rate Limits guide](/developers/guides/rate-limits) for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
components:
  schemas:
    DocumentWithoutSegments:
      type: object
      properties:
        id:
          type: integer
          description: A unique number identifying the Document.
          example: 46530
        project_id:
          type: integer
          description: A unique number identifying the Project.
          example: 287
        srclang:
          type: string
          description: An ISO 639-1 language identifier.
          example: en
        trglang:
          type: string
          description: An ISO 639-1 language identifier.
          example: de
        name:
          type: string
          description: The document name.
          example: Introduction.xliff
        import_in_progress:
          type: boolean
          description: True if the document is currently being imported
          example: false
        import_succeeded:
          type: boolean
          description: True if the import process succeeded.
          example: false
        import_error_message:
          type: string
          description: Error message if `import_succeeded=false`
          example: Could not parse XML.
        export_in_progress:
          type: boolean
          description: True if the document is currently being exported for download
          example: false
        export_succeeded:
          type: boolean
          description: True if the export process succeeded.
          example: false
        export_error_message:
          type: string
          description: Error message if `export_succeeded=false`
          example: Could not parse XML.
        is_pretranslating:
          type: boolean
          description: True if the document is currently being pretranslated.
          example: false
        status:
          type: object
          properties:
            pretranslation:
              type: string
              description: ''
              example: idle
              enum:
              - idle
              - pending
              - running
          description: A list of translations for the query term.
          example:
            pretranslation: idle
        translator_email:
          type: string
          description: The email of the assigned translator.
          example: translator@example.com
        reviewer_email:
          type: string
          description: The email of the assigned reviewer.
          example: reviewer@example.com
        customer_reviewer_email:
          type: string
          description: The email of the assigned customer reviewer. Only present if the project was request by id.
          example: reviewer@example.com
        created_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        updated_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        is_review_complete:
          type: boolean
          description: Document review status.
          example: true
      description: 'A Document is a collection of zero or more Segments.

        '
    Segment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: A unique number identifying the Segment.
          example: 84480010
        created_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        updated_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        document_id:
          type: integer
          description: A unique Document identifier.
          example: 1234
        memory_id:
          type: integer
          description: The Memory with which this Segment is associated.
          example: 5678
        source:
          type: string
          description: The source string.
          example: The red bus.
        srclang:
          type: string
          description: An ISO 639-1 language code.
          example: en
        target:
          type: string
          description: The target string.
          example: Le bus rouge.
        trglang:
          type: string
          description: An ISO 639-1 language code.
          example: fr
        is_confirmed:
          type: boolean
          description: The confirmation status.
          example: true
        is_reviewed:
          type: boolean
          description: The review status.
          example: true
      description: 'A Segment is a source string and, optionally, its translation. A Segment can be associated with both a Memory and a Document. The Segment object contains additional metadata about the source and target strings.

        '
    DocumentWithSegments:
      type: object
      properties:
        id:
          type: integer
          description: A unique number identifying the Document.
          example: 46530
        project_id:
          type: integer
          description: A unique number identifying the Project.
          example: 287
        srclang:
          type: string
          description: An ISO 639-1 language identifier.
          example: en
        trglang:
          type: string
          description: An ISO 639-1 language identifier.
          example: de
        name:
          type: string
          description: The document name.
          example: Introduction.xliff
        import_in_progress:
          type: boolean
          description: True if the document is currently being imported
          example: false
        import_succeeded:
          type: boolean
          description: True if the import process succeeded.
          example: false
        import_error_message:
          type: string
          description: Error message if `import_succeeded=false`
          example: Could not parse XML.
        export_in_progress:
          type: boolean
          description: True if the document is currently being exported for download
          example: false
        export_succeeded:
          type: boolean
          description: True if the export process succeeded.
          example: false
        export_error_message:
          type: string
          description: Error message if `export_succeeded=false`
          example: Could not parse XML.
        is_pretranslating:
          type: boolean
          description: True if the document is currently being pretranslated.
          example: false
        status:
          type: object
          properties:
            pretranslation:
              type: string
              description: ''
              example: idle
              enum:
              - idle
              - pending
              - running
          description: A list of translations for the query term.
          example:
            pretranslation: idle
        translator_email:
          type: string
          description: The email of the assigned translator.
          example: translator@example.com
        reviewer_email:
          type: string
          description: The email of the assigned reviewer.
          example: reviewer@example.com
        created_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        updated_at:
          type: integer
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          example: 1489147692
        is_review_complete:
          type: boolean
          description: Document review status.
          example: true
        segments:
          type: array
          description: A list of Segments.
          items:
            $ref: '#/components/schemas/Segment'
      description: 'A Document is a collection of zero or more Segments.

        '
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable message describing the error.
      description: 'Response in the event of an unexpected error.

        '
      example:
        message: Internal server error.
  responses:
    UnauthorizedError:
      description: Unauthorized
      content:
        application/octet-stream:
          schema:
            type: string
        text/plain:
          schema:
            type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      name: key
      in: query