/
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.

az.png

  1. OPTIONAL: Fill in the following query parameters:

  • jobIds → IDs of the jobs that you want to start.

  1. Click the Send button and run the request.

ba.png

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

bb.png

cURL for the method

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/workflow/start?jobIds=$JOBIDS' \ # Insert your project id into the URL as well as job ids as query parameters -H 'Authorization: XTM-Basic $TOKEN' # Your basic token

Uploading a new source file to an existing project

This method can be used to upload new source files to a project or replace existing ones (continuous project update).

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

What details are required?

  • Project ID → ID of an XTM Cloud project to which you want to upload source files.

bc.png

Running the method in Postman

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

bd.png

  1. Change the {projectId} part in the URL to the ID of the project to which you want to upload source files.

be.png

  1. Apply the Header parameter with the authentication token.

bf.png

  1. OPTIONAL: There are two optional query parameters that are quite important:

  • matchType → specifies whether a file that has the same name as an existing file, in the project, will replace that file or be uploaded separately. To perform continous project updates in the project, use this setting: matchType=MATCH_NAMES.

  • reanalyseProject → specifies all other, existing files in the project are reanalyzed when the method is run. If this parameter is set to NO, only uploaded files will be analyzed.

  1. Change the body type to form-data and upload the file.

bg.png

To upload multiple files, use the files[n].file structure in which n is an incremental value that starts at 0.

  1. Click the Send button and run the request.

bh.png

Information about the jobs in the project, including newly uploaded files is displayed. The project will start analyzing the uploaded files, which should be displayed in the XTM Cloud UI.

bi.png

cURL for the method

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/files/sources/upload' \ # Insert your project id into the URL -H 'Authorization: XTM-Basic $TOKEN' \ # Your basic token -F 'files[0].file=@"$PATH"'

Useful tips for prompt engineering

What is cURL?

cURL is a command-line tool that is used to transfer data to or from a server, using a variety of protocols, with HTTP and HTTPS being the most common. It is widely used by developers and testers for interacting with APIs, automating requests and troubleshooting web services.

Why is cURL useful?

  • It is available on nearly every Unix-based system and can also be used on Windows.

  • It enables you to send HTTP requests (GET, POST, PUT, DELETE, etc.) from the command line or within scripts.

  • You can include headers, authentication tokens, request bodies and query parameters easily.

How does cURL helps with prompt automation?

When combined with AI-powered tools or prompt automation systems, cURL becomes a bridge between generated prompts and real-world API calls. For example:

  • you can generate dynamic cURL commands with placeholders (e.g. {{TOKEN}}, {{USER_ID}}) that AI tools can fill in on the fly.

  • prompt engineers can automate common workflows (such as posting data, retrieving results, or chaining API calls) using predefined cURL templates.

  • AI models can be instructed to generate working cURL examples from API documentation, helping non-technical users execute tasks quickly.

Using cURL examples with AI tools

AI tools can streamline the way you use cURL examples from this documentation dramatically. Instead of modifying commands manually, each time, you can leverage AI to dynamically adapt, generate and execute cURL requests based on your input or context.

How it works

When you see a cURL example in this documentation – such as the one for checking a project’s status—you can use AI to:

  • replace placeholders (e.g. $PROJECTID, $TOKEN) automatically by providing relevant variables in natural language.

  • customize query parameters (like fetchLevel=STEPS) depending on your current needs, without memorizing syntax.

  • convert cURL commands to other tools such as Postman collections or Python requests scripts on demand.

  • chain multiple requests together, enabling end-to-end workflows (e.g. get project status → if status is "IN_PROGRESS", retrieve job details).

Example use case with AI prompting

As an example, imagine you want to get the status of project ID 123456 and include job details. You can prompt an AI tool with:

"Generate a cURL command to check the status of project 123456 with fetchLevel set to JOBS, using my XTM token abc123xyz."

The AI can instantly produce:

curl -L -g 'https://api.xtm-cloud.com/project-manager-api-rest/projects/123456/status?fetchLevel=JOBS' \ -H 'Authorization: XTM-Basic abc123xyz'

No need to remember syntax, format headers or search for documentation every time.

Why this matters

This matters because it:

  • saves time, especially when someone is working with many endpoints or switching environments.

  • reduces errors: placeholder replacements are often a source of bugs. AI can handle them consistently.

  • enables non-technical users to interact with your API: even users without command-line experience can interact with your API using natural language + AI tooling.

This approach works well whether you are:

  • testing individual endpoints.

  • automating repetitive workflows.

  • or building internal tools with dynamic request templates.

How can I obtain the cURL for my method from Postman?

When an API method has been prepared in Postman, you can easily change it into cURL for automation.

  1. Prepare the method that you want to export as cURL.

image-20250423-112303.png

  1. Navigate to the Code button on the right-hand side.

image-20250423-112401.png

  1. Change the Code snippet type to cURL.

image-20250423-112426.png

  1. Copy the contents or use the Copy snippet button and paste the contents in the automation, whre they can be used.

image-20250423-112458.png

Tips for prompt engineering with AI tools

When working with APIs and automation, prompt engineering – the process of crafting effective instructions for AI tools – becomes a crucial skill. Whether you are generating cURL commands, formatting requests or asking an AI assistant to interact with an API, a well-written prompt can mean the difference between accurate output and frustration.

Below are proven tips to improve your prompt design when working with AI tools in the context of API usage:

1. Be specific about your intentions

Vague prompts often lead to incomplete or incorrect results. Instead of writing:

“Create an API call for project status”

Say:

“Generate a cURL command to check the status of project ID 123456 in XTM Cloud, with fetchLevel=JOBS and a placeholder for the API token.”

The more detail you include, the more accurate and useful the AI's response will be.

2. Use realistic examples

Give the AI concrete values to work with (e.g. fake tokens, IDs, URLs), even if you plan to replace them later. This helps the AI understand structure and context.

Example:

curl -H "Authorization: XTM-Basic abc123xyz" \ "https://api.xtm-cloud.com/project-manager-api-rest/projects/123456/status?fetchLevel=BUNDLES"

3. Ask for placeholders or reusable templates

If you plan to reuse the result in a script or system, tell the AI to generate a template, not a hard-coded value.

Prompt:

“Generate a reusable cURL command for getting project status, with placeholders for project ID and token.”

Output:

curl -H "Authorization: XTM-Basic $TOKEN" \ "https://api.xtm-cloud.com/project-manager-api-rest/projects/$PROJECTID/status?fetchLevel=JOBS"

4. Include the output format you expect

If you want the AI to return the result as raw JSON, formatted script, or even Markdown documentation, say so in your prompt.

Example:

“Return the cURL example in a Markdown code block with a short explanation.”

5. Use iterative refinement

Start simple. If the output is close, but not quite right, clarify your intentions. AI tools are responsive to iterative guidance such as:

“Add a timeout header to the previous cURL request.”

6. Test and validate AI output

AI can be helpful, but it is not infallible. Always review generated requests - check URL paths, method types and parameters before executing, especially when working with production environments.

Pro tip:
Keep a set of high-quality prompts and AI-generated snippets that worked well. These can become a shared library for your team, speeding up development and reducing friction when working with APIs.

Guidelines for safe and effective AI integration

Integrating AI tools into your API workflows can significantly boost productivity, speed up development and reduce manual errors. However, without clear boundaries and safeguards, it can also introduce inconsistencies or even security risks. To make the most of AI while maintaining control, it is essential to follow a few key guidelines.

1. Always review AI-generated code before use

Never copy and execute AI-generated code blindly, especially in production environments. AI tools can misunderstand context or generate incorrect paths, methods, or headers.

What to do:

  • Run AI-generated requests in a sandbox or testing environment first.

  • Check for typos, malformed JSON or incorrect use of query parameters.

  • Validate endpoint behavior manually or via your documentation.

2. Use placeholder tokens and IDs

Real secrets such as API tokens or sensitive project IDs must not be revealed to AI. Instead, use clearly-marked placeholders. This avoids accidental credential leaks and makes the output reusable across multiple scenarios.

3. Limit AI to read-only or safe operations first

Start by using AI to help with GET requests or read-only operations. These are far less likely to cause unintended damage.

Initially avoid:

  • DELETE or PUT operations

  • bulk updates or anything irreversible

  • direct integration with production data

4. Log and track what AI generates

If you are incorporating AI into your development environment, logging the prompts and responses is vital for debugging and future improvements.

Why this helps:
You can trace back to find out which prompt has caused particular behavior, identify patterns in failures and refine prompt strategies accordingly.

5. Use AI as a copilot, not a replacement

AI is great for accelerating workflows, but it is not a substitute for developer intuition or API understanding.

Keep this mindset:

“AI helps me get there faster, but I am still driving the car.”

6. Keep security and compliance in mind

If you are using AI in sensitive environments (e.g. healthcare, finance, or internal tools), ensure that:

  • you are not feeding sensitive or regulated data into third-party models.

  • your usage complies with your organization’s data protection policies.

  • any AI outputs are reviewed and approved by authorized personnel before deployment.