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.

• Your username is the string displayed in Account ID field.

• Your password is an API key generated by clicking CREATE NEW KEY in the API Keys pane. Note that you can create multiple keys, if required.

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.

Rate limits

All Smartcat API methods have a rate limit of 4 requests per second.

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:

• smartcat domain is the URL of the corresponding Smartcat server:
  • for the European server, use https://smartcat.ai/
  • for the American server, use https://us.smartcat.ai/
  • for the Asian server, use https://ea.smartcat.ai/
• resource is the name of a Smartcat object

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:

• Add, update, and delete objects
• Obtain data from your account

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.

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.

   

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.

   

7. Select the workflow stages for your project.

   

8. Add the pretranslation rules of your preference.

   

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/:

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:

• You have a dynamically changing list of source and target languages
• Your projects are of very different nature and have different settings, that is pretranslation rules, stages, assignees and so on
• You are using an external system that is unable to work in continuous mode and expects the translation system project lifecycle to be internally managed.

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'.

Click the Edit button on a newly created translation profile.

Copy the ID from the url.

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

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.