Smartling provides RESTful APIs for many of the actions available through the Smartling UI, allowing you to automate your translation process.
API categories
The table below provides an overview of the available public APIs.
API URL
Hostname
The API hostname is:
api.smartling.com
Path
The path to specific API endpoints is structured as follows:
/<service>-api/<version>/<authorization root>/<resources-and-optional-parameters>
The authorization root is generally either 'accounts' followed by an account ID, or 'projects' followed by a project ID.
For example:
https://api.smartling.com/accounts-api/v2/accounts/677dfe99/projects https://api.smartling.com/files-api/v2/projects/453a3d5a2/file/status?fileUri=xyz
Request format
The REST API is accessed by sending HTTP requests to the required API endpoints, and processing the resulting HTTP responses.
All requests, except for authentication and token refresh, must include a valid access token in an HTTP header as well as an appropriate content-type header. In general, POST and PUT requests use Content-Type: application/json.
API parameters are included in the request URI, the query parameters, the request body, or some combination of these, depending on the endpoint being called.
Array query parameters
In most cases, arrays in query parameters should be specified without square brackets. Instead, simply repeat the parameter:
/projects/{projectId}/resource?foo=bar&foo=qux
However, some legacy APIs may still use square brackets:
/projects/{projectId}/resource?foo[]=bar&foo[]=qux
Refer to the API reference documentation to determine which one is required.
Responses
Responses to successful requests contain JSON content in this format:
{
"response": {
"code": "SUCCESS",
"data": {
}
}
}
The contents of the data node in the response varies depending on the endpoint and the results of the request, and may in some cases by null.
Errors
Error responses have a 4xx or 5xx HTTP status code. When this happens, the response bodies look like the following:
{
"response": {
"code": "ERROR_CODE",
"errors": [
{
“key”: “error.key”,
“message”: “Error message”,
“details”: {
“field”:”value”
}
}
]
}
}
The structure of the details node varies depending on the endpoint, and in some cases may be null.
For more information, see Error Handling.
Date formats
All dates are represented as strings using the ISO-8601 date standard in UTC.
Pattern:
yyyy-MM-dd'T'HH:mm:ss'Z'
Example:
2020-11-21T01:51:17Z
Authentication
To use the API, you must first authenticate by sending a user ID and secret to the authentication endpoint. This will return an access token and a refresh token. The access token is then included in a header in subsequent requests. The access token expires and must be refreshed periodically using the refresh endpoint. For more details, see Authentication.
Rate limits
To maintain service availability, two kinds of limits are applied to API usage: a maximum request rate and a maximum number of concurrent requests. Counting can be per user, project and/or account, depending on which endpoint is being accessed, and the maximum values vary by endpoint.
When a rate limit is hit by an API client, the server sends an HTTP 429 MAX_OPERATIONS_LIMIT_EXCEEDED response, along with details of the specific limit. If this happens, the client should pause requests for a time, and then retry. For more details, see Rate Limits.
Pagination
List-type endpoints that result in a large result set (for example, ‘list all jobs within an account’) divide the response data into pages and return a single page per response. The caller specifies which page to send by using the limit and offset API parameters. For more details, see Pagination.
Asynchronous processes
For requests that take a long time to process, such as processing a large file upload, the API returns a 202 ACCEPTED response, meaning that the work has started but not completed. To know when such a process is complete, the client must poll a separate status endpoint. For some common situations, such as adding files to a job, helper APIs that handle some of the status checking are available (e.g., job batches).
Webhooks
Webhooks can be configured via API for various events, such as ‘translation completed’. When these events occur, a Smartling service sends an HTTP request to the configured callback URL. GET and POST requests are supported, in addition to signed requests. For more details, see Webhooks and Callbacks.
SDKs
We are currently reassessing our SDK offering and will have additional information on this soon.