Smartcat Document API

openapi: 3.2.0
info:
  title: Smartcat Account Document API
  version: v1
servers:
- url: /
tags:
- name: Document
paths:
  /api/integration/v1/document:
    get:
      tags:
      - Document
      summary: Fetch the document details
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      responses:
        '200':
          description: Request has been successfully completed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DocumentModel'
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentModel'
            text/json:
              schema:
                $ref: '#/components/schemas/DocumentModel'
        '404':
          description: The provided document ID or language ID does not exist
        '403':
          description: The document is not associated with the account
    delete:
      tags:
      - Document
      summary: Delete one or several documents
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentIds
        in: query
        description: Array of document IDs
        required: true
        schema:
          type: array
          items:
            type: string
            description: ID of the document translation
      responses:
        '204':
          description: Documents have been successfully deleted
        '400':
          description: The provided array of document IDs is empty
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: 'Returns if:


            - At least one document is not associated with the account

            - The document is assigned to a vendor who is not allowed to update documents in the assigned projects'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/translate/status:
    get:
      tags:
      - Document
      summary: Fetch the status of adding document translation
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      responses:
        '200':
          description: Request has been successfully completed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TranslationTaskStatus'
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationTaskStatus'
            text/json:
              schema:
                $ref: '#/components/schemas/TranslationTaskStatus'
        '403':
          description: At least one document is not associated with the account
        '404':
          description: The provided document ID does not exist
  /api/integration/v1/document/translate/result:
    get:
      tags:
      - Document
      summary: Fetch a detailed report on translation import results
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/statistics:
    get:
      tags:
      - Document
      summary: Fetch statistics
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      - name: onlyExactMatches
        in: query
        description: Specifies whether returning 100% and higher matches will suffice
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Request has been successfully completed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DocumentStatisticsModel'
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStatisticsModel'
            text/json:
              schema:
                $ref: '#/components/schemas/DocumentStatisticsModel'
        '202':
          description: Statistics creation is in progress
        '403':
          description: The document is not associated with the account
        '422':
          description: A provided document could not be disassembled
  /api/integration/v1/document/assignFreelancers:
    post:
      tags:
      - Document
      summary: Divide the document into equal blocks by the number of words and assign one block to each specified freelancer
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        schema:
          type: string
          description: ID of the document translation
      - name: stageNumber
        in: query
        description: Workflow stage number
        schema:
          type: string
      requestBody:
        description: Assigned freelancers' user IDs
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                type: string
                format: uuid
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
          text/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
          application/*+json:
            schema:
              type: array
              items:
                type: string
                format: uuid
      responses:
        '204':
          description: Freelancer has been successfully assigned to the document
        '400':
          description: ' Returns if:


            - The document was not disassembled or was disassembled, but contains 0 words

            - The provided workflow stage number does not exist in the project

            - An assignment has been already made to the specified workflow stage

            - A freelancer ID was not found in CAT'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: The document is not associated with the account
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The provided document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/assignVendors:
    post:
      tags:
      - Document
      summary: Assign a vendor to a document workflow stage
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        schema:
          type: string
          description: ID of the document translation
      - name: stageNumber
        in: query
        description: Workflow stage number
        schema:
          type: string
      - name: vendorAccountId
        in: query
        description: Vendor account ID
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Vendor has been successfully assigned to the document
        '400':
          description: Document disassembly failed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: 'Returns if:


            - The document is not associated with the account

            - The account is a vendor'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: 'Returns if:


            - The provided document ID does not exist

            - The provided workflow stage number does not exist in the project

            - A vendor ID was not found in CAT

            - The client-to-vendor connection does not exist'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: An assignment has been already made to the specified workflow stage
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/setStageUnitCount:
    post:
      tags:
      - Document
      summary: Specify the unit count for a document workflow stage
      parameters:
      - name: projectId
        in: query
        description: Project ID
        schema:
          type: string
          format: uuid
      - name: stageNumber
        in: query
        description: Workflow stage number
        schema:
          type: string
      - name: targetLanguageId
        in: query
        description: Document target language ID
        schema:
          type: integer
          format: int32
      requestBody:
        description: Document unit count setup model
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SetStageUnitsCountModel'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SetStageUnitsCountModel'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SetStageUnitsCountModel'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SetStageUnitsCountModel'
      responses:
        '204':
          description: Unit count has been successfully applied to a document workflow stage
        '400':
          description: 'Returns if:


            - The documents are not associated with the project

            - The stage is internal

            - The unit count is already set for the stage'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: ' Returns if:


            - The project is not associated with the account and the account is not a project vendor

            - The document is not associated with the account and the vendor is not assigned to the stage'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: ' Returns if:


            - The provided project ID does not exist

            - The provided workflow stage number does not exist in the project'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/assign:
    post:
      tags:
      - Document
      summary: Specify the linguist assignment and segment distribution model
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format. \n\nAssignmentMode option descriptions:\n\n- AssignmentMode.DistributeAmongAll: Distribute segments among all the assigned linguists\n\n- AssignmentMode.Rocket: Send invitations and assign all unassigned segments to the first linguist who accepts\n\n- AssignmentMode.InviteOnly: Only invite linguists, segments will be assigned later manually\n\nNote: If the segment count is not specified, the task will be equally divided among all linguists\n"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        schema:
          type: string
          description: ID of the document translation
      - name: stageNumber
        in: query
        description: Workflow stage number
        schema:
          type: string
      requestBody:
        description: Assignment request - list of assigned executors
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/AssignExecutivesRequestModel'
          application/json:
            schema:
              $ref: '#/components/schemas/AssignExecutivesRequestModel'
          text/json:
            schema:
              $ref: '#/components/schemas/AssignExecutivesRequestModel'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AssignExecutivesRequestModel'
      responses:
        '204':
          description: Linguist has been successfully assigned to the document
        '400':
          description: 'Returns if:


            - The document was not disassembled or was disassembled, but contains 0 words

            - The provided workflow stage number does not exist in the project

            - An assignment has been already made to the specified workflow stage

            - A freelancer ID was not found in CAT

            - The specified assignment type is unknown

            - Internal account users (not freelancers) were assigned to AssignmentMode.Rocket or AssignmentMode.InviteOnly

            - The workflow stage is accomplished outside of Smartcat and its word count/cost are not set (exception: for an in-house freelancer setting word count/cost is not mandatory)'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: 'Returns if:


            - The project is not associated with the account

            - The project is associated with the account, but was assigned to a vendor'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The provided document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/unassign:
    post:
      tags:
      - Document
      summary: Unassign a linguist
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        schema:
          type: string
          description: ID of the document translation
      - name: stageNumber
        in: query
        description: Workflow stage number
        schema:
          type: string
      requestBody:
        description: Unassigned executor ID
        content:
          application/json-patch+json:
            schema:
              type: string
          application/json:
            schema:
              type: string
          text/json:
            schema:
              type: string
          application/*+json:
            schema:
              type: string
      responses:
        '204':
          description: Linguist has been successfully unassigned
        '400':
          description: 'Returns if:


            - The provided workflow stage number does not exist in the project

            - The linguist with the specified ID is not assigned to the document workflow stage'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: 'Returns if:


            - The project is not associated with the account

            - The project is associated with the account, but was assigned to a vendor'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The provided document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/assignFromMyTeam:
    post:
      tags:
      - Document
      summary: 'Send Rocket invitations to MyTeam linguists:

        send invitations, assign the first one to accept the job to every unassigned document segment'
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      requestBody:
        description: MyTeam linguists assignment model
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/AssignMyTeamExecutivesRequestModel'
          application/json:
            schema:
              $ref: '#/components/schemas/AssignMyTeamExecutivesRequestModel'
          text/json:
            schema:
              $ref: '#/components/schemas/AssignMyTeamExecutivesRequestModel'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AssignMyTeamExecutivesRequestModel'
      responses:
        '200':
          description: The operation has been successfully completed
          content:
            text/plain:
              schema:
                type: integer
                format: int32
            application/json:
              schema:
                type: integer
                format: int32
            text/json:
              schema:
                type: integer
                format: int32
        '403':
          description: 'Returns if:


            - The project is not associated with the account

            - The project is associated with the account, but was assigned to a vendor'
        '400':
          description: 'Returns if:


            - The input model is not provided

            - No document is specified

            - The specified documents have different target languages

            - The specified documents are associated with different projects

            - The document was not disassembled or was disassembled, but contains 0 words

            - The provided workflow stage number does not exist in the project

            - An assignment has been already made to the specified workflow stage

            - The workflow stage is accomplished outside of Smartcat and its word count/cost are not set (exception: for an in-house freelancer setting word count/cost is not mandatory)'
        '404':
          description: The provided document ID does not exist
  /api/integration/v1/document/complete:
    post:
      tags:
      - Document
      summary: Change the document status to Completed
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        schema:
          type: string
          description: ID of the document translation
      responses:
        '200':
          description: The operation has been successfully completed
        '204':
          description: The document is already in Completed status
        '400':
          description: The document status is not "Manager Review"
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The specified document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v2/document/update:
    put:
      tags:
      - Document
      summary: Update the specified document
      description: "UpdateDocumentModel must have exactly one file. All other fields in model are optional. \n"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
      - name: disassembleAlgorithmName
        in: query
        description: Optional algorithm for file disassembly
        schema:
          type: string
      - name: presetDisassembleAlgorithm
        in: query
        description: Optional preset for the file disassembly algorithm
        schema:
          type: string
      requestBody:
        description: Document with a file update model
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                value:
                  $ref: '#/components/schemas/UploadDocumentPropertiesModel'
                files:
                  type: array
                  items:
                    type: string
                    format: binary
        required: true
      responses:
        '200':
          description: Request has been successfully completed
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentModel'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentModel'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentModel'
        '400':
          description: The specified file is empty
        '403':
          description: ' Returns if:


            - At least one document is not associated with the account

            - The document update functionality is not enabled in the account

            - The document is assigned to a vendor who is not allowed to update documents in the assigned projects'
        '404':
          description: The provided document ID does not exist
  /api/integration/v1/document/rename:
    put:
      tags:
      - Document
      summary: Rename the assigned document
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      - name: name
        in: query
        description: New name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The document has been successfully renamed
        '403':
          description: At least one document is not associated with the account
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The provided document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: The new name will not be unique in the project
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/integration/v1/document/updateMetaInfo:
    put:
      tags:
      - Document
      summary: Update document meta info
      description: "Document ID is represented as `{documentId}_{languageId}`, \nwhere `{documentId}` identifies the document id in string format,\nand `{languageId}` identifies its target language in numeric format"
      parameters:
      - name: documentId
        in: query
        description: Document ID
        required: true
        schema:
          type: string
          description: ID of the document translation
      requestBody:
        description: New value
        content:
          application/json-patch+json:
            schema:
              type: string
          application/json:
            schema:
              type: string
          text/json:
            schema:
              type: string
          application/*+json:
            schema:
              type: string
        required: true
      responses:
        '202':
          description: Accepted
        '403':
          description: At least one document is not associated with the account
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The provided document ID does not exist
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '204':
          description: Document meta info has been successfully updated
  /api/integration/v1/document/translate:
    put:

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smartcat/refs/heads/main/openapi/smartcat-document-api-openapi.yml