If you are new to the XTM API, the official documentation might seem overwhelming at first glance. This article is designed to guide you through it step by step, helping you understand how the documentation is structured, how to find what you need, and how to start using the XTM API effectively.

Whether you are a developer, project manager, or technical user who is exploring automation options, this guide will help you become familiar with the key parts of the documentation and make your first API calls with confidence.

In the sections that follow, you will learn how to access the documentation for your specific XTM Cloud instance, use the search and navigation tools, understand authentication options, explore the available XTM API resources, and read method definitions. We will also cover how to make sense of request and response structures, using the built-in references.

Let's get started by learning how to access the XTM API documentation for your instance.

General information

Before you start using the XTM API, it is important to know where to find the correct documentation for your specific instance. Each XTM Cloud instance can have slightly different methods for doing so, depending on its version or configuration, so accessing the right documentation is essential.

To view the API documentation for your instance, simply add /rest-api to the end of your XTM URL. This will open interactive documentation that lists all available API methods for your XTM environment.

For example:

• For the XTM Cloud instance, the documentation is located at:
  https://xtm.cloud/rest-api

• For a dedicated instance, the URL might look like this:
  https://yourcompany.xtm-intl.com/rest-api

Using your instance-specific documentation ensures that you are always referring to the most accurate and up-to-date list of methods, parameters, and response formats available to you. This is especially important because new features and methods might be added in different XTM Cloud releases.

Table of Contents and search

On the left-hand side of the XTM API documentation, you will find the Table of Contents, which organizes all available API methods in clear categories such as Projects, Users, Customers, Workflows and more. These categories are tailored to your XTM Cloud instance and reflect just the methods that are available in your environment.

Each section can be expanded to show the methods it contains. For example, under User subject matters, you will find the Obtain the user's subject matters method with which you can retrieve a user’s specialization data via the API.

At the top of the menu is a search bar, which is a very helpful tool when you are looking for a specific method. You can type in a keyword such as user, project, or language and the documentation will be filtered instantly, to list the relevant sections and methods. This is especially useful when you are not sure where a method is located or want to avoid scrolling through the full list.

Using the Table of Contents and search bar effectively can save you a lot of time and help you navigate the XTM API documentation with ease.

Before you can start using most of the XTM API methods, you need to authenticate your requests. The Authentication Methods section of the documentation provides an overview of the available options for authorizing access to the API.

Three authentication methods are supported:

• OAuth 2.0 → A secure token-based standard which is often used for integrating with third-party systems or when working with user content flows.

• XTM-Basic → A simpler method that uses a combination of a client name, password, and user ID to generate a token. This token is then used to authorize further requests.

• SAML → Typically used in enterprise environments where Single Sign-On (SSO) is configured.

For beginners or for basic API usage, we recommend starting with XTM-Basic authentication. It is the most straightforward option and enables you to test and explore the XTM API quickly, using tools such as Postman. You can find more details and examples under the XTM-Basic section in the documentation.

Once you generate a token using one of the supported methods, include it in the Authorization header of your API requests, to access protected endpoints.

The API Resources section in the XTM API documentation organizes information about resources used in API methods.

Callbacks

Callbacks enable XTM Cloud to send automated notifications to your system when certain events, such project creation, job completion or due date changes, occur, This section lists all available callbacks and the authentication methods for them. Callbacks can be set during project creation or for all projects created for a particular XTM Cloud customer, or set globally on the backend, by XTM Support.

Definitions

This section contains key terms that you will see throughout the XTM API.

HTTP Codes

Common response codes from the API:

• 200 OK → Success.

• 201 Created → Resource created.

• 400 Bad Request → There is an issue with an API request. Verify your request and make sure the data it contains is correct. If it is throwing a Processing has failed error and you have verified the request, the issue might be on the XTM side.

• 401 Unauthorized → Invalid or missing credentials. This usually means that the token you are using has either been passed incorrectly or the token itself is incorrect.

• 403 Forbidden → Access denied. This means that the instance is blocking your access, which usually happens when it is behind a VPN or another form of security.

• 404 Not Found → Resource does not exist. This means that whatever you are trying to do does not exist. This can be occur when an attempt is made to download a file that does not exist in XTM Cloud.

• 405 Method not supported → Please check the method type and make sure that POST or GET is set as described in the documentation for this method.

• 422 Unprocessable Entity → Required fields are missing. In the request, some fields that are required (marked by an asterisk) might be missing.

• 500/503 → Server error or temporary unavailability. This is most often an issue on the XTM Cloud side. If you do not see anything wrong with the request, report this to XTM Support for further investigation.

These sections provide essential context for understanding how XTM Cloud communicates, both via API responses and via automated callbacks.

The Methods section is the most essential part of the XTM API documentation. It provides everything you need to know, to run a specific API method successfully from your environment. Each method is described in a standardized format, which helps you understand what it does, what inputs it requires, and what outputs it returns. Below, you will find an explanation of the key elements that you will see when you view a method.

Description

A short explanation of what the method does. Please pay close attention to the description as it might contain information about how parameters might change the response within the request.

Open

Open

Authorizations

This section specifies which user roles have permission to run the method. Some methods are restricted to Project Managers (PMs), while others can be accessed by Linguists or other roles, depending on the permissions.

Open

Path Parameters

These are dynamic parts of the URL that you must replace with your own data.
For example:

Open

/projects/{projectId}/target-languages → You must replace {projectId} with the actual ID of the project you want to query.

Query Parameters

Values that you can include in the request URL to filter or modify the result. In Postman, you add these in the Params tab screen. The documentation will tell you:

1. the name of the parameter.

2. the data type (e.g., string, int).

3. if the paramater is required or optional.

4. possible accepted values.

Open

Open

Header Parameters

Headers are additional fields which are sent with the request, most commonly used for authentication.
In XTM Cloud, you almost always need to include the following:

• Authorization: XTM-Basic YOURTOKEN if you are using Basic token for authentication,

• Authorization: Bearer YOURTOKEN if you are using OAuth token.

Open

Request Body

The Request Body section provides detailed information about the data that needs to be included in the body of your request. This is relevant for methods that use POST, PUT or similar HTTP methods that send data to the server.

These are the key elements:

• Request Body Schema → This tells you what format the body should be in. The most common types are:

Open

Open

Open

Open

• The request body includes a list of parameters that can be passed, each with a description and value type (e.g., string, int or boolean). This part has a similar structure to query parameters and helps you understand which fields are required and how to format them.

Each parameter will be listed with its:

1. Name.

2. Data type.

3. Description and possible inputs if Enum is provided.

4. Whether it is required.

Open

Responses

This section shows what kind of responses you can expect. It includes:

• HTTP status codes (e.g., 200 OK, 400 Bad Request).

• Example response bodies.

• Structure and field names that will be contained in the returned JSON.

Open

URL

Each XTM API method in the documentation has a URL, which is the full endpoint that you need to call, to use the method. This URL is built from the base path of your XTM Cloud instance (e.g., https://api.xtm-cloud.com) and the specific path for the method. For example, the URL for the Obtain metrics that match specific criteria method is /projects/{projectId}/metrics.

You will need to replace any placeholders (such as {projectId}) with real values before making the request.

Another important part of the URL is the method type that should be used. The most common ones are POST and GET, but PUT, DELETE and PATCH can also be used in XTM API methods.

Open

Open

Request samples

The Request samples section is especially useful when you are working with methods that require a POST, PUT, or any other request with a body – typically in application/json format.

This section provides a prebuilt example of the request body with default or placeholder values. You can copy it directly from the documentation, paste it into your request tool (such as Postman), and then adjust the values according to your needs.

Using these samples saves time, reduces errors and helps you understand what fields are expected by the method.

Open

Open

Response samples

The Response samples section shows a realistic example of the response you will receive when the method is executed successfully.

This section contains values that might be used in some of the API methods. For example, Language Codes contains all available language codes that you will be able to use when creating a project via API.

This section contains the API changes that were introduced in current and previous XTM Cloud versions.