API Guides

When to use Smartcat API

Smartcat's simple, powerful, convenient, and secure API (Application Programming Interface) provides programmatic access to the Smartcat features from third-party applications. It is designed to operate as a full-fledged equivalent and even an extension to the Smartcat user interface. Such fundamental processes as the automatic creation of translation projects, status tracking, the download of the translated texts, etc. are easily completed using Create, Retrieve, Update, and Delete methods.

To use this document, you should have a basic familiarity with software development and the Smartcat user interface.

Any functionality described in this guide is available if you are logged in to a company account. You will not be able to use API from a freelancer account.

Authorization and authentication

As any other set of credentials, API credentials consist of a username and a password. To obtain them, log in to your Smartcat account as an Administrator and nagivate to Settings > API.

project

The Smartcat API uses the primary Basic Authentication scheme for every method. Each request must be prefixed with the Authorization: Key header, where Key is a Base64 encoded "userName":"password" string.

API call basics

The API allows you to access the resources and methods available in the system directly. This approach uses the standard Web methods, such as GET, PUT, POST, and DELETE, to retrieve, create, update and delete from the different Smartcat objects needed.

In general, the resources are accessible using the following format:

https://smartcat.domain/api/integration/v1/resource

Where:

For example, the full URL for a project list request will look as follows:

https://smartcat.ai/api/integration/v1/project/list

Methods

API methods represent specific operations, also referred to as API calls, that you can invoke to perform tasks, for example:

Smartcat performs validation on the data submitted within each API call before committing changes to your account data. POST (Create)

The POST method is used to add new objects to your account.

GET (Retrieve)

This method allows you to retrieve or search data in your account. You can specify a single object ID or a list of IDs to retrieve an array of objects.

PUT (Update)

The PUT method updates objects in your account using the information submitted within the request.

DELETE

The DELETE method accepts an object type and ID and is used to purge objects from your account.

Response codes and error messages

The REST API responds to each request with an HTTP status code that indicates success or error.

The table below provides details of status codes, typical scenarios, and what information can be expected in the response body.

HTTP status code Description
200 OK This general response code indicates that the request was accepted and the response contains result. For GET requests, it means that the response body contains the quested resource or data. For PUT requests, it means that the operation has completed successfully, and the response body contains information about the result.
202 IN PROGRESS The request has been accepted for processing, but the processing has not been completed. This is usually received for asynchronous operations.
204 OK The operation has completed successfully, but there is no additional information to send in the response body. This code is usually received for DELETE requests.
400 BAD REQUEST Some aspect of the request was not valid. The response body contains information about the request and includes an error message.
403 FORBIDDEN Indicates that the user does not have sufficient permissions to access the requested resource. An attempt to access a resource that does not belong to the specified entity may also result in this error.
404 NOT FOUND The target resource does not exist. This might happen because the URI is invalid, or the resource has been deleted.
409 CONFLICT A conflicting change has been detected during an attempt to modify a resource. The response body provides further information.
422 CANNOT PROCESS The content type of the request entity and the syntax of the request entity are valid and correct, but the server was unable to process the contained instructions.

Creating a project and importing a document

In Smartcat, a project is the entity where you store files, define source and target languages (yes, we support multilingual projects), set deadlines, attach linguistic assets, and connect machine translation.

For starters, let's create a project that contains the most basic data: the name and source/target languages. There are many more parameters you can experiment with later, so your first project created through the API will have only the fundamental ones. The method required to create a project is POST project/create method. Keep in mind that the parameter assignToVendor must be passed to request the method successfully.

    [
      {
        "name":" API Project",
        "sourceLanguage": "en",
        "targetLanguages": ["ru"],
        "assignToVendor": false
      }
    ]

You can upload a document while creating a project using the documentProperties model. Alternatively, you can create an empty project and skip the documentProperties model. To import a file into an existing project, use the method

POST project/ document/update?documentId={documentId_languageId}

Most parameters are optional for the basic scenario and can be safely ignored for now.

Updating a document

It is quite usual for a continuous translation scenario to have a newer document version. If you indeed have an updated document, you can update it in your project using the PUT document/update method with the document ID.

https://smartcat.ai/api/integration/v1/document/update?documentId={documentId_languageId}

The corresponding document will be overwritten in Smartcat. All completed translations will be inserted in the new document through pretranslation.

Calculating statistics

In some cases, you will need to calculate how many words your document has and how many of them are translation memory matches. To do this, use the following method:

GET project/{projectId}/statistics?onlyExactMatches=false

Note that the statistics will be calculated for all documents in the project. If you need statistics for a specific document, use

GET document/statistics?documentId={documentId_languageId}&onlyExactMatches=false

If you only need the overall word count without translation memory matches, simply use the wordsCount parameter returned by the GET document?documentId={documentId_languageId} method.

Tracking translation status

You can fetch information about your document at any time: progress for each workflow stage, task status, assignments, and so on. To get this information for a specific document, use GET document with the corresponding document ID:

GET document/statistics?documentId={documentId_languageId}&onlyExactMatches=false

To fetch information about the progress and statuses of all your documents with the overall project status and progress into the bargain, use GET project/{projectid} with the corresponding project ID.

Exporting a translation

To export a translated document, use a POST document/export request:

document/export?documentIds={documentId_languageId}&type=target&stageNumber=1

This requests Smartcat to render the final document. For smaller documents, you’ll receive the task ID in the response. For larger ones, rendering the target file will take some time depending on the document size and server load. In this case, Smartcat will send you a callback with the task ID to <callbackURL>/document/exportRequestCompleted once the exported document is ready.

NOTE: The stageNumber parameter defines a number of a stage in your project workflow. For example, 1 is for Translation if it is the first stage, 2 is for Editing, and so on.

Integrating with a permanent Smartcat project

In order to streamline your integration with Smartcat by API you can use permanent projects for importing and exporting documents from them.

This is particularly handy when a specific source language, a static set of target languages and documents of the same type are going to be processed with the same settings all the time.

To implement that type of integration, you have to manually create a Smartcat project, and then upload documents, track their status and export the translation through the API.

The following sections describe each of these steps in detail.

Create a permanent project for the API integration

To create a permanent project, proceed as follows:

  1. Log in to to your Smartcat account.

  2. To start the project creation process, click the Plus (+) button next to Projects in the left menu bar or the Create Project button in the workspace.

    project

  3. Click Skip when prompted to upload documents.

  4. Enter the project name and select the source language and target languages of the project. Please note that after you create a project, you can add translation languages, but cannot change or remove any languages you have already chosen.

  5. To enable machine translation for a project, check the Use machine translation box. If you choose to use machine translation, by clicking on the Settings wheel, you will have an option to choose one of the many engines that are integrated with Smartcat. This option is rather flexible and allows users to assign different engines to each language in order to benefit from the best possible MT output.

  6. To set up translation memories, glossaries and quality assurance checks, use the Advanced Settings switch.

    project

  7. Select the workflow stages for your project.

    project

  8. Add the pretranslation rules of your preference.

    project project

  9. Click Finish. Your project has been successfully created.

You can find more details on Smartcat projects here.

Collect the Project ID

To configure the integration, you will require the Smartcat project ID. This is the unique identifier assigned automatically when a project is created in Smartcat. It consists of 36 characters (including hyphens).

To collect the Project ID, open the project page and copy the part of the address line after /project/:

project

Prepare the API credentials

To prepare the API credentials, refer to the Authorization and authentication section

Upload a document for translation

To import a file into an existing project, use the POST project/document method.

[
    {
        "key": "file",
        "type": "file",
        "src": "/D:/projects/smartcat/temp/test.txt"
    },
    {
        "key": "documentModel",
        "value": "[
            {
              "externalId": "1232456789",
              "metaInfo": "",
              "disassembleAlgorithmName": "",
              "presetDisassembleAlgorithm": "",
              "bilingualFileImportSetings": {
                "targetSubstitutionMode": "all",
                "lockMode": "none",
                "confirmMode": "none"
              },
              "targetLanguages": [
                "ru"
              ],
              "enablePlaceholders": true,
              "enableOcr": true
            }
        ]",
        "contentType": "application/json",
        "type": "text"
    }
]

Update a document

If you have a newer document version (which is quite usual for a continuous scenario), you can update it in your project using the PUT document/update method and the document ID. The corresponding document will be overwritten in Smartcat. All translations that have already been done will be inserted in the new document through pretranslation.

[
    {
        "key": "file",
        "type": "file",
        "src": "/D:/projects/smartcat/temp/test.txt"
    },
    {
        "key": "updateDocumentModel",
        "value": "{
            "bilingualFileImportSetings": {
                "targetSubstitutionMode": "all",
                "lockMode": "none",
                "confirmMode": "none"
            },
            "enablePlaceholders": true
        }",
        "contentType": "application/json",
        "type": "text"
    }
]

Track the document status

You can fetch information about your document at any time: progress for each workflow stage, task status, assignments, and so on. To retrieve this information for a specific document, use GET document with the corresponding document ID.

To retrieve information about the progress and statuses of all your documents at once and the overall project status and progress, use GET project/{projectid} with the corresponding project ID.

Export the translation

To export a translated document, use a POST document/export request. This instructs Smartcat to render the final document. For smaller documents, you will receive the task ID in the response. For larger ones, rendering the target file will take some time depending on the document size and server load. In this case, Smartcat will send you a callback with the task ID to <callbackURL>/document/exportRequestCompleted once the exported document is ready.

https://smartcat.com/api/integration/v1/document/export?documentIds=f1e5e09a8ad7830434cc477d_25&documentIds=de0b3b432ad7837175dcfeb3_25&mode=current&type=source&stageNumber=1

The stageNumber parameter defines the stage index in your project workflow. For example, 1 is for Translation if it is the first stage, 2 is for Editing, and so on.

Integrating with a temporary Smartcat project

The most common way of API integration with Smartcat is by using a permanent project.

However, temporary projects can also be used for integration in the following cases:

The downside of this approach is that there are certain project settings, such as MT engine mapping or advanced pretranslation rules, that cannot be set up via API.

As usual, prior to using API you need to generate a set of API credentials and choose the appropriate Smartcat domain.

The process typically involves the following steps:

  1. Create a project
  2. Upload the files
  3. Export the translation
  4. Delete a project

Instant translations via the real-time API

If you need translations to be delivered instantly to your live application, you can use Smartcat real-time API. Just make a simple request with a piece of text you need to translate and get the translation in response.

To use the real-time translation API, do the following:

Go to your Smartcat account, open 'Settings/Smart translation profiles'.

Click 'Add smart translation profile'. Enter the name, comments and select the MT engine that will be used for making translations. Hit 'Save'.

profile

Click the Edit button on a newly created translation profile.

profile

Copy the ID from the url.

profile

Use that ID in a request described here: Smart translation

As usual, prior to using the API you need to generate a set of API credentials and choose the appropriate Smartcat domain.

Notification callbacks

How to use callbacks to get notifications when the status of a document or project changes in Smartcat

You can use callbacks to get notifications when the status of a document or project changes in Smartcat, and to get the status of importing bilingual XLIFF versions of documents.

Configuration for receiving callbacks

In order to get notification callbacks, you need to follow these steps:

  1. Configure the web server.

  2. Configure the callback URL for WebAPI.

  3. Configure notifications using the API methods described below.

  4. Process the callback request when a project's status changes. URL: <callbackURL>/project/status

  5. Process the callback request when a document's status changes. URL: <callbackURL>/document/status

  6. Process the callback request to finish importing a translation from an XLIFF. URL: <callbackURL>/document/translationImportCompleted

Project status request structure:
POST /api/callback/project/status HTTP/1.1
Host: example.local
Content-Type: application/json`
["1e2d703f-9def-4d27-ab4d-350cbbe8c44b", "b5bf9123-31b3-4e45-9ee9-8c14d15a4145"]
Document status request structure:
POST /api/callback/document/status HTTP/1.1
Host: example.local
Content-Type: application/json`
["189_25", "310_25"]
Translation importing status request structure:
POST /api/callbackUrl/document/translationImportCompleted HTTP/1.1
Host: example.local
Content-Type: application/json`
["60606_25", "61234_25"]

If some of the notifications from the queue were sent but some could not be delivered, the undelivered notifications are put in the retry queue.

Interval for resending notifications if Smartcat cannot access the callback URL: 30-second delay with 8 attempts; the delay doubles for each subsequent attempt.

Please see the API description for setting up the callbacks: API Callback

Note that you can use additionalHeaders parameter, which adds an HTTP header to the notifications. This HTTP header can be useful if the web server is behind a firewall and authentication is necessary. If this is not the case, you can ignore the additionalHeaders parameter.