/
Often-used API Methods with Examples

Often-used API Methods with Examples

API method examples

IMPORTANT!
In the examples below, we have omitted token generation and authentication. For details of how to generate a Basic token, see the Running your first API method article.

Links to the API documentation are provided for the Cloud instance. If you are using another instance, use the URLs for that instance. For more details, see the Understanding the API Documentation.

Creating a project via the API

This section will guide you through the process for creating a simple project via the API.

Link to the documentation for the method: https://api.xtm-cloud.com/project-manager-api-rest/#tag/Project/operation/createProject.

You can see that the XTM API documentation for the project creation method does not describe required fields in the body. This is not 100% accurate, as some fields are required, but depend on whether a project template is specified during project creation. Consequently, two examples are provided below: one without a project template, and one with a project template. Both examples will also have a file attached, even though it is not required when a project is created via the API.

Creating a project without a project template

What details are required?

  • Customer ID → XTM Cloud customer for which the project will be created:

  • Workflow definition name → Workflow definition that will be used in the project. (Instead of a workflow definition name, an ID can be used, with the workflowId parameter.):

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type to POST.

Untitled1.png

  1. Apply the Header parameter with the authentication token.

Untitled2.png

  1. Change the body type to form-data.

Untitled3.png

  1. Fill the following body parameters:

  • name → Project name that will be used.

  • customerId → Customer for which the project will be created.

  • workflowName → Workflow definition name. This workflow will be applied in the project.

  • sourceLanguage → Source language code that will be used in the project. Available language codes can be found in the API documentation.

  • targetLanguages → Target language codes that will be used in the project.

  • translationFiles[0].file → Not required: attach source file to the project. Remember to change the field type to File, from the default Text.

Untitled4.png

  1. Click the Send button and run the request.

Untitled5.png

The project should be created correctly and be visible in XTM Cloud.

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects' \ -H 'Authorization: XTM-Basic $TOKEN' \ # Basic token obtained from the auth method -F 'name="My first project"' \ # Name of your project -F 'customerId="$CUSTOMERID"' \ # ID of a customer you will be using -F 'workflowName="translate"' \ # Name of the workflow that the project will have -F 'sourceLanguage="en_US"' \ # Source language code -F 'targetLanguages="de_DE"' \ # Target language code, can be multiple divided by a comma -F 'translationFiles[0].file=@"$PATH"' # Path to uploaded file

Creating a project using a template

What details are required?

  • Customer ID → XTM Cloud customer for which the project will be created:

  • Template ID → ID of the project template that the project will use:

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toPOST.

Untitled11.png

  1. Apply the Header parameter with the authentication token.

Untitled22.png

  1. Change the body type to form-data.

Untitled33.png

  1. Fill the following body parameters:

  • name → Project name that will be used.

  • customerId → Customer for which the project will be created.

  • templateId → Template that will be used in the project.

  • translationFiles[0].file → Not required: attach source file to the project. Remember to change the field type to ‘File’, from the default ‘Text’.

Untitled44.png

  1. Click the Send button and run the request.

Untitled55.png

The project should be created and available in XTM Cloud.

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects' \ -H 'Authorization: XTM-Basic $TOKEN' \ # Basic token obtained from the auth method -F 'name="My first project"' \ # Name of your project -F 'customerId="$CUSTOMERID"' \ # ID of a customer you will be using -F 'templateId="$TEMPLATEID"' \ # ID of the template. Languages and workflows will be taken from the template unless present in the request -F 'translationFiles[0].file=@"$PATH"' # Path to uploaded file

Generating a target file

This guide describes how to generate target files for an XTM Cloud project. If required, the procedure below can be modified easily, to enable other types of file to be generated.

Link to the API documentation for the method: https://api.xtm-cloud.com/rest-api/#tag/Project-files/operation/generateFiles.

Generating target files for all jobs in a project

What details are required?

  • Project ID → ID of the XTM Cloud project for which you want to generate the target files.

Untitled6.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toPOST.

Untitled111.png

  1. Change the {projectId} part in the URL to the project ID of the project for which you want to generate target files.

Untitled222.png

  1. Apply the Header parameter with the authentication token.

Untitled333.png

  1. Fill in the following query parameter:

  • fileType → TARGET

  1. Click the Send button and run the request.

Untitled444.png

You will obtain the file ID in the response. In the XTM Cloud UI, target file generation will start for all jobs in the project.

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/generate' \ # ID of the project needs to be replaced -H 'Authorization: XTM-Basic $TOKEN' \ # Your basic token -F 'fileType="TARGET"' # File type

Generating target files for an individual job in a project

What details are required?

  • Project ID → ID of the XTM Cloud project for which you want to generate the target files.

  • Job ID → ID of the job for which you want to generate a target file.

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toPOST.

1.png

  1. Change the {projectId} part in the URL to the project ID of the project for which you want to generate target files.

2.png

  1. Apply the Header parameter with the authentication token.

3.png

  1. Fill in the following query parameters:

  • fileType → TARGET.

  • jobIds → Job ID of the job for which you want to generate a target file.

  1. Click the Send button and run the request.

4.png

You will obtain the file ID in the response and target file generation will start, but only for the job specified in the request.

If you wish, you can enter multiple job IDs in this request, to generate multiple target files at once.

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/generate' \ # ID of the project needs to be replaced -H 'Authorization: XTM-Basic $TOKEN' \ # Your basic token -F 'fileType="TARGET"' \ # File type -F 'jobIds="$JOBID"' # IDs of the job

Obtaining the status of generated files

This section describes how to check whether a file has finished generating in XTM Cloud.

Link to the Documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-files/operation/filesStatus

Using a file ID

What details are required?

  • Project ID → ID of an XTM Cloud project for which files have been generated.

  • File ID – ID of a previously generated file, obtained using the generate file API request.

221.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toGET.

23.png

  1. Change the {projectId} part in the URL to the project ID of the project in which you want to check the status of target files.

24.png

  1. Apply the Header parameter with the authentication token.

25.png

  1. Fill in the following query parameters:

  • fileIds → File ID of the file whose status you want to check.

  1. Click the Send button and run the request.

26.png

You will obtain the status of the file generation in the response. Usually, the response is IN_PROGRESS, meaning that a file is still being generated, or FINISHED, when the file has finished being generated and is ready for download

If you wish, you can enter multiple file IDs in this request, to check multiple files at once.

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/status?fileIds=$FILEIDS' \ # Fill in your project ID and files IDs -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Without a file ID

What details are required?

  • Project ID → ID of an XTM Cloud project for which the target files have been generated.

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toGET.

a.png

  1. Change the {projectId} part in the URL with the project ID of the project in which you want to check the status of target files.

b.png

  1. Apply the Header parameter with the authentication token.

c.png

  1. Fill in the following query parameters:

  • fileType → Type of the file you want to check (TARGET, in this example).

  • fileScope → Enter JOB to check the status of individual jobs or PROJECT to check the status of all the files in the project.

  1. Click the Send button and run the request.

d.png

You will obtain the status of the file generation in the response. Usually, the response is IN_PROGRESS, meaning that a file is still being generated, or FINISHED, when the file has finished being generated and is ready for download

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/status?fileType=TARGET&fileScope=JOB' \ # Replace project ID with an ID of your project -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Downloading a generated file

Use this method to download previously-generated files.

Link to the Documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-files/operation/downloadFile or https://api.xtm-cloud.com/rest-api/#tag/Project-files/operation/downloadFiles
In the examples below, the second method – Download project files – is used.

Using a file ID

What details are required?

  • Project ID → ID of an XTM Cloud project from which you want to download files.

e.png

  • File ID → ID of a previously-generated file, obtained using the generate file API request.

f.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toGET.

g.png

  1. Change the {projectId} part in the URL to the project ID of the project from which you want to download the target files.

h.png

  1. Apply the Header parameter with the authentication token.

i.png

  1. Fill in the following query parameters:

  • fileIds → File ID of the file you want to download.

  • fileType → Type of file you will attempt to download. In this example: TARGET.

  1. Click the Send button and run the request.

j.png

You will obtain the generated files in the response. To download the generated files to your computer, select the Save response to a file button.

k.png

The downloaded target files are saved in a ZIP file, which you can open to access them.

l.png

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/status?fileType=TARGET&fileIds=$FILEIDS' \ # Replace project ID with an ID of your project and FILEIDS with IDs of the files from the generation method -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Without a file ID

What details are required?

  • Project ID → ID of an XTM Cloud project from which you want to download files.

m.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toGET.

n.png

  1. Change the {projectId} part in the URL to the project ID of the project from which you want to download the target files.

o.png

  1. Apply the Header parameter with the authentication token.

p.png

  1. Fill in the following query parameters:

  • fileScope → Scope of the files that are to be downloaded. Enter JOB to download the files for individual jobs or PROJECT to download the files for all project jobs.

  • fileType → Type of file you will attempt to download. TARGET in this example.

  • jobIds → Only required if the fileScope setting is JOB.

  1. Click the Send button and run the request.

r.png

You will obtain the generated files in the response. To download the generated files to your computer, select the Save response to a file button.

s.png

The downloaded target files are saved in a ZIP file, which you can open to access them.

t.png

cURL for the method

curl -L 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/download?fileType=TARGET&fileScope=PROJECT' \ # Insert your project id into the URL -H 'Authorization: XTM-Basic $TOKEN' # Your Basic token

Obtaining the project analysis status

This method can be used to check if the project is still being analyzed.

Link to documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-states/operation/checkProjectAnalysisCompletion.

What details are required?

  • Project ID → ID of an XTM Cloud project whose analysis status you want to check.

u.png

Running the method in Postman

  1. POST.GET.

w.png

  1. Change the {projectId} part in the URL to the project ID of the project whose analysis status you want to check.

y.png

  1. Apply the Header parameter with the authentication token.

z.png

  1. OPTIONAL: Fill in the following query parameters:

  • fetchLevel →Specify JOBS to see the analysis status of all individual jobs. If you run the method without JOBS, you will just see the status for the entire project.

  1. Click the Send button and run the request.

aa.png
ab.png

Look for the Status in the response for the analysis status for this project. IN_PROGRESS means that it is still being analyzed. FINISHED means that the project is ready for further action.

cURL for the method

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/analysis' \ # Insert your project id into the URL -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Obtaining a project status

This method can be used to check a project’s overall status.

Link to documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-states/operation/checkProjectStatuses.

What details are required?

  • Project ID – ID of an XTM Cloud project whose status you want to find out.

ac.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toGET.

ad.png

  1. Change the {projectId} part in the URL to the project ID of the project whose overall status you want to check.

ae.png

  1. Apply the Header parameter with the authentication token.

af.png

  1. OPTIONAL: Fill in the following query parameters:

  • fetchLevel → JOBS/STEPS/BUNDLES – set one of these settings to get much more detail about jobs, steps or bundles, in the method.

  1. Click the Send button and run the request.

ag.png

You will see the status of the project according to the specifiedfetchLevel.

cURL for the method

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/status?fetchLevel=STEPS' \ # Insert your project id into the URL -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Linguist assignment via the API

This method can be used to assign users to an XTM Cloud project.

Link to documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-workflows/operation/assignUser

What details are required?

  • Project ID → ID of an XTM Cloud project to which you want to assign Linguists.

ah.png

  • User ID → ID of the user that you want to assign.

ai.png

  • (Optional) Job ID → Specify this if you want to assign the user to a specific job, not the entire project.

aj.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toPOST.

ak.png

  1. Change the {projectId} part in the URL to the project ID of the project to which you want to assign Linguists.

al.png

  1. Apply the Header parameter with the authentication token.

am.png

  1. Copy the json sample request from the documentation and paste it into the Body (Raw → Json).

an.png
ao.png

  1. In the body, edit the content so that it contains the data you require.

ap.png

If you are sending a request without jobIds, assigning a Linguist to every step in the entire project, make sure that the Linguist has the necessary language and step permission set beforehand. If the permissions are not correct, the API response will return an error message to inform you.

  1. Click the Send button and run the request.

ar.png
as.png

A message will inform you about whether the job has been assigned successfully. The assignment should change in the UI.

cURL for the method

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/workflow/assign' \ # Insert your project id into the URL -H 'Authorization: XTM-Basic $TOKEN' \ # Your basic token -H 'Content-Type: application/json' \ -d '[ { "user": { "id": $USERID, "type": "INTERNAL_USER" }, "jobIds": [ $JOBID ] } ]'

Starting a project workflow via the API

This method can be used to start a project or selected jobs within it.

Link to documentation for this method: https://api.xtm-cloud.com/rest-api/#tag/Project-workflows/operation/startWorkflow.

What details are required?

  • Project ID → ID of an XTM Cloud project in which you want to start the workflow.

at.png

  • (Optional) Job ID → To start a specific job, you need its ID.

au.png

Running the method in Postman

  1. Copy the URL from the documentation and paste it in. Change the method type toPOST.

aw.png

  1. Change the {projectId} part in the URL to the project ID of the project in which you want to start the workflow.

ay.png

  1. Apply the Header parameter with the authentication token.