The purpose of this article is to answer common questions about the API module in XTM Cloud and to help resolve issues you might experience with it.

Can I quantify the resources used by API call traffic on the server? What does the influx of API calls mostly affect?

XTM Cloud does not record any statistics that could give reliable answers about your traffic and underlying resources. Project analysis can be overloaded if there are many project creation calls in a short period of time. However, this will mostly affect the processing module, not the main part of the application, and it should still work at a normal pace. The only effect is that projects that are created later will have to wait for previous projects to be analyzed first. We also recommend that a limiter is implemented so that the system is not flooded.

I want to implement some API-based automation in project workflows in which I use the XTM Cloud instance as a subcontractor. Is it possible to configure callbacks for when a new project is created or reaches a particular workflow step that is assigned to us?

Since callbacks are configured on the contractor’s side during project creation, it is not possible to either implement them for just a specific part of the workflow or set them up as an LSP.

Sometimes we cannot create an XTM Cloud project via the REST API because it throws the following error: statuscode: 400 {"reason":"Incorrect parameters were passed.","incorrectParameters":"DESCRIPTION"}. What could be the reason?

The XTM Cloud project description limit is 2000 characters and this value cannot be changed or modified. This limitation applies both to creation of the project via the API and the XTM Cloud UI.

Open

Is there a REST API method for starting a project automatically?

There is a REST API method that can be used to start a project’s workflow. For more information, refer to our official REST API documentation about this specific method: REST API - Start workflow in project.

Is there a REST API method for obtaining specific rate cards?

There are two REST API methods with which you can obtain rate cards that match specific criteria for the following:

• USER: Obtain USER rate cards that match specific criteria;

• LSP: Obtain LSP rate cards that match specific criteria.

Is there a REST API method for importing specific rate cards for Linguists into XTM Cloud?

Unfortunately, there is no REST API method that would enable you to import specific rate cards for Linguists into XTM Cloud.

Is there a REST API method for changing a project workflow?

There is a REST API method with which you can change a project’s workflow, by managing the project’s workflow steps. For possible approaches, see this list of available REST API methods: Project workflows.

Is there a REST API method for obtaining a user ID?

Unfortunately, there is no REST API method for this purpose at the moment.

Is there a REST API method for creating a project template in XTM Cloud?

There is a REST API method with which you can create a project template in XTM Cloud. For details, see the following method: Create new project template.

If I am not using a project template, which parameters do I need to include?

Workflow ID/name, source language, and target language. An example of how to create a project without a template can be found above.

How do I include callbacks in a project and which ones do I need?

To include callbacks when creating a project via the XTM API, you can pass them as part of the request body, using the following structure:

callbacks.jobFinishedCallback[0].url

Replace jobFinishedCallback with the specific callback type you need. Some commonly-used callback types include:

• jobFinishedCallback – triggered when a job is completed.

• projectCreatedCallback – triggered when the project is created.

• projectFinishedCallback – triggered when the entire project is completed.

You can add multiple callbacks by including their corresponding keys and URLs in the callbacks object.

Open

Open

Is there a limit to the amount of files or file size I can include?

There is no limit to the amount of files in the request. Additional files can be specified in this array: translationFiles[n].file, n has to be in ascending order from 0 – translationFiles[0].file, translationFiles[1].file, translationFiles[2].file, etc.

As far as uploading files via the API is concerned, there is no actual size limitation. You should see a timeout after some time, but the software will continue the file upload process.

What are the possible project/job statuses? Which status means that I should keep querying the status, which means I should abort, and which means I can proceed?

The XTM API uses different status values depending on the method – these can apply to project analysis, project state, job state, and more. Understanding these statuses will help you decide whether to continue waiting, retry, proceed or stop your integration logic.

Example: Analysis Status

If you are checking the project analysis status and the reported status is IN PROGRESS, it means that analysis is still ongoing. Many subsequent API methods (e.g. generating costs or accessing metrics) will not work until the status changes to FINISHED.

Always refer to the method-specific documentation, as some status values can vary slightly depending on the context (project, job, analysis, etc.).

How often should I query status checks for projects in analysis?

In this special case, there is no specific recommended frequency, as it depends on your integration and the number or size of projects being processed. It is good practice to query a project’s analysis status every 10 to 15 minutes. In any case, to avoid overloading the XTM API, we recommend that you do not exceed 50 GET requests per minute.

That said, a more efficient solution is to use analysisFinishedCallback. This callback is triggered automatically when analysis is complete, so your system can proceed without the need to poll the API repeatedly.

Using callbacks helps reduce load and makes your integration more responsive.

Is there a way to start a workflow automatically? How do I assign Linguists to a project automatically without using the API?

The easiest way to start the workflow automatically is to create a project template. Bear in mind that for Automatic start to work, the first step in the workflow must also be assigned. You can do so in the same tab screen: Projects → Templates → template → Workflow.

Open

How can I tell whether a project is finished? How can I tell whether individual jobs, steps or bundles are finished?

There are two main ways to determine if a project has been completed:

1. Use the "Obtain project status" method

You can call the Check Project Statuses endpoint.
In the response, look for the completionStatus field. When it shows FINISHED, the project is fully completed.
You can also use fetchLevel parameter to distinguish between jobs, bundles or steps in the project and check their completion statuses.

2. Set up the projectFinishedCallback

This callback will automatically be triggered and sent to your specified URL when the last job in the project is completed. It is a more efficient option as it eliminates the need to poll the API.
Setting up jobFinishedCallback can be useful if you need to know exactly when individual jobs are finished.

Using callbacks is recommended for real-time updates and reducing the number of API requests.

How can I finish a project automatically?

The best way to finish projects automatically, considering they are finished during creation (for example all matches are ICE or segments are MT translated), is to set the Automatically finish steps where all segments are green/done setting in the XTM Cloud project template.

Open

Please bear in mind that, for this to work, the project must be assigned automatically and started in the project template as well.

An API method to finish workflows will be introduced in future XTM Cloud versions.

What is a job ID? Where can I find it?

The job ID for every XTM Cloud job (file for a target language in a project) is a unique identifier. It is used in numerous XTM API methods.

The job ID can be found in the UI: see Additional job details in the project workflow:

Open

Open

Alternatively, use this API method: ‘Obtain project status’ XTM Connect SDK – REST API with fetchLevel=JOBS.

What is the difference between displayStepNames and stepReferenceNames?

displayStepNames refer to the names of workflow steps as seen by the user, in the UI. These are more "visual" or user-friendly names that are intended to make the workflow easier to understand at a glance.

On the other hand, stepReferenceNames are internal identifiers used by XTM Cloud to reference workflow steps in the back end. These names are not visible in the XTM Cloud UI but are used in the logic and data structure for the workflow. They are essential for system operations and consistency.

In some cases, the stepReferenceName can differ from the displayStepName, for example by having a number appended at the end. This can happen if a step is deleted and then added again, or if the workflow definition is modified after the project is created.

While some API methods still use name (displayStepName), the recommended practice is to use stepReferenceName wherever possible, as this ensures consistency and avoids potential issues with name duplication or changes in the display label.

What is the difference between the JOB and PROJECT fileScope parameters?

If you specifyPROJECT, the system tries to generate the files for all jobs in the project, or download them, at once.

Open

Even if files are available for separate jobs, but files have not been generated for the entire project, it is not possible to use fetchLevel=PROJECTto fetch the existing files for separate jobs.

If you specify JOB,the system tries to download a file that has been generated for an individual job.

Open

How do I obtain a file ID?

The file ID is a unique identifier that is required for certain API methods, especially those related to downloading files from XTM Cloud.

You can obtain the file ID from the response from file generation methods. For example, when you generate a target file using the API, the response will include a fileId field. This value can then be used in subsequent methods to check the file’s status or to download the file once it is ready.

Always store the file ID from the response if you plan to interact with the file again later in your workflow.

What happens if I send a request without passing the file ID?

It depends on which method you are using. In some cases, the file ID is required and the request can fail or return an error if it is missing.

However, in the case of file download methods, if you do not specify the file ID, XTM Cloud will attempt to return the newest file that meets all required conditions (for example status, language, step).

For full control and consistency, it is always recommended to use the file ID when available.

What are enums?

Enums (short for enumerations) are the predefined sets of values that an API method will accept for a specific parameter. When a parameter is marked as an enum in the documentation, it means you can only use one of the listed values – any other value will result in an error.

For example, in some methods, you might see a parameter such asmetrics that accepts an enum with values SHOW or HIDE.

If you pass anything else, such asVISIBLE, ON or a lowercase version of those texts, the API will reject the request.

Enums are listed clearly in the method documentation, in the parameter description. Always make sure that you match the exact value and capitalization as shown.

Using the correct enum values ensures your request is valid and understood by the XTM API.

Open

How do array types work in the form-data body request?

Open

When an array is required in a multipart/form-data request body (as shown in the documentation), it must follow a specific naming convention:

arrayName[n].key

• arrayName:the name of the field (e.g. files).

• n: the index of the array element, starting from 0.

• key: the property of the object you are passing.

Example:
If you are passing a list of files and want to specify the name property of the first file, the key should be:

files[0].name

To include multiple files with individual names, you would structure it like this:

files[0].name = "file_one.txt"
files[1].name = "file_two.txt"

Each files[n] object must include all 'required' fields defined in the schema.

Costs cannot be generated using REST API (400). What does the following error message mean: "reason": "Incorrect parameters were passed.", "incorrectParameters": "COSTS_OPTION"?

Most likely, the issue stems from the fact that the ID of the user you are using to generate costs is not set as a Dummy user for cost generation and so it cannot be used in the REST API request that way.

Therefore, make sure you select the relevant checkbox in the user settings, in the XTM Cloud UI [Users → User list → (select a user) → General → Dummy user for cost generation].

Open