Smartcat Document API

openapi: 3.0.1
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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- At least one document is not associated with the account\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- The document was not disassembled or was disassembled, but contains 0 words\r\n- The provided workflow stage number does not exist in the project\r\n- An assignment has been already made to the specified workflow stage\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- The document is not associated with the account\r\n- 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:\n\r\n- The provided document ID does not exist\r\n- The provided workflow stage number does not exist in the project\r\n- A vendor ID was not found in CAT\r\n- 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:\n\r\n- The documents are not associated with the project\r\n- The stage is internal\r\n- 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:\n\r\n- The project is not associated with the account and the account is not a project vendor\r\n- 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:\n\r\n- The provided project ID does not exist\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\nand `{languageId}` identifies its target language in numeric format. \n\r\nAssignmentMode option descriptions:\n\r\n- AssignmentMode.DistributeAmongAll: Distribute segments among all the assigned linguists\n\r\n- AssignmentMode.Rocket: Send invitations and assign all unassigned segments to the first linguist who accepts\n\r\n- AssignmentMode.InviteOnly: Only invite linguists, segments will be assigned later manually\n\r\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:\n\r\n- The document was not disassembled or was disassembled, but contains 0 words\r\n- The provided workflow stage number does not exist in the project\r\n- An assignment has been already made to the specified workflow stage\r\n- A freelancer ID was not found in CAT\r\n- The specified assignment type is unknown\r\n- Internal account users (not freelancers) were assigned to AssignmentMode.Rocket or AssignmentMode.InviteOnly\r\n- 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:\n\r\n- The project is not associated with the account\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- The provided workflow stage number does not exist in the project\r\n- 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:\n\r\n- The project is not associated with the account\r\n- 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:\r\nsend invitations, assign the first one to accept the job to every unassigned document segment"
      description: "Document ID is represented as `{documentId}_{languageId}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- The project is not associated with the account\r\n- The project is associated with the account, but was assigned to a vendor"
        '400':
          description: "Returns if:\n\r\n- The input model is not provided\r\n- No document is specified\r\n- The specified documents have different target languages\r\n- The specified documents are associated with different projects\r\n- The document was not disassembled or was disassembled, but contains 0 words\r\n- The provided workflow stage number does not exist in the project\r\n- An assignment has been already made to the specified workflow stage\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:\n\r\n- At least one document is not associated with the account\r\n- The document update functionality is not enabled in the account\r\n- 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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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}`, \r\nwhere `{documentId}` identifies the document id in string format,\r\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:
      tags:
      - Document
      summary: Translate the specified document using the specified translation file
      description: "Available only for the file formats that support true updates (currently these are resource files with unique resource IDs) \n\r\nSets a task to processing. When the API call is completed, the translation might be not finished yet \n\r\nDocument

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