API Guides (developer portal)
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.
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: 1. for the European server, use https://smartcat.ai/ 1. for the American server, use https://us.smartcat.ai/ 1. 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.
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 AI 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 /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:
Log in to to your Smartcat account.
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. 
Click Skip when prompted to upload documents.
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.
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 AI translation output.
To set up translation memories, glossaries and quality assurance checks, use the Advanced Settings switch. 
Select the workflow stages for your project. 
Add the pretranslation rules of your preference.  
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 /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 AI translation 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:
Upload the files
Export the translation
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 thetranslation 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: AI 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:
Configure the web server.
Configure the callback URL for WebAPI.
Configure notifications using the API methods described below.
Process the callback request when a project's status changes. URL: /project/status
Process the callback request when a document's status changes. URL: /document/status
Process the callback request to finish importing a translation from an XLIFF. URL: /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.