Smartling provides both REST and GraphQL APIs for many of the actions available through the Smartling UI, allowing you to automate your translation process. The REST APIs cover the broadest range of actions and are the most commonly used, while the GraphQL APIs offer flexible, query-based access for specific use cases such as content search and translation memory.

The complete Smartling API reference documentation can be found on the API Reference Site. GraphQL reference documentation is available on the GraphQL Reference Site.

Check out our best practices guide for a comprehensive overview of key considerations for building and designing API integrations.

Please note that Smartling’s API is a paid resource. For pricing information, please contact your Smartling Customer Success Manager.

API categories

The table below provides an overview of the available public REST APIs.

GraphQL APIs

In addition to the REST APIs, Smartling offers GraphQL APIs for query-based access to specific areas of the platform. GraphQL lets you request exactly the fields you need in a single call, which is well suited to searching and filtering large sets of content. The table below lists the currently available public GraphQL APIs.

The GraphQL APIs are served from the same api.smartling.com host and use the same token-based authentication as the REST APIs (see Authentication below). Each GraphQL service exposes a single endpoint that ends in /graphql, for example:

  https://api.smartling.com/strings-view-service-graphql-api/v2/projects/<projectId>/graphql
  https://api.smartling.com/tm-graphql-api/v2/accounts/<accountUid>/graphql

For the full schema, available queries and mutations, and examples, see the GraphQL Reference Site.

API URL

The following sections describe the REST API.

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. The same access token is used for both the REST and GraphQL APIs. 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).

Callbacks and webhooks

Smartling supports both callbacks and webhooks. Callbacks can be configured via API for various events, such as ‘translation completed’. When these events occur, the 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 on each service, please see their respective documentation: Smartling Callbacks, Smartling Webhooks Overview.

SDKs

Smartling provides SDKs that simplify the use of the REST APIs by offering idiomatic, language-specific client libraries. Coverage and level of ongoing support vary by language. The Java SDK offers the broadest coverage, aiming to support all public REST APIs, while the Python and Node.js SDKs cover the most commonly needed APIs, such as Jobs and Files. Legacy SDKs (.NET, PHP, Ruby, Go) and a CLI tool are also available.

For the full list of SDKs and links to each, see Smartling SDKs Overview.