---
title: REST API - Defining a Trace in the Request Body
slug: rm/rest-api-defining-a-trace-in-the-request-body
docTags: 
createdAt: 2026-06-09T13:38:46.062Z
---

The following services require you to define/specify a trace in the request body:

- [REST API - Add Traces Request](docId\:niYBWusc5pG3rM7SZ_JPl)
- [REST API - Delete Traces Request](docId\:sHPeL8IZwQZEgECy0R1kU) 
- [REST API - Move Artifact Request](docId\:oDiK9tdoaeir5GGgG28ms) 

In the request body you must specify:

- The other artifact in the trace relationship (for [REST API - Add Traces Request](docId\:niYBWusc5pG3rM7SZ_JPl) and [REST API - Delete Traces Request](docId\:sHPeL8IZwQZEgECy0R1kU) requests)
  OR
- The new parent trace (for [REST API - Move Artifact Request](docId\:oDiK9tdoaeir5GGgG28ms))

# Parameters

You must specify a `Traces` element first to contain any individual traces you want to specify by using the `Trace` element. Here is an example in XML:

:::CodeblockTabs
PHP-TEMPLATE

```php
<Traces>
<Trace>
</Trace>
<Trace>
</Trace>
</Traces>
```
:::

The following parameters can be specified within each  element you are specifying:

- `ArtifactId`: The ID of the artifact whose trace relationship is being defined.
- `SubArtifactId`: The ID of the sub-artifact whose trace relationship is being defined.
- `ProjectId`: The ID of the project of the artifact whose trace relationship is being defined.
- `Type`: Defines the type of trace. The valid values are the following:
  - `Manual`: Only applicable when adding or deleting a trace.
  - `Parent`: Only applicable when moving an artifact.
- `Direction`: The direction of the trace. The valid values are the following:
  - `To`: From the artifact in the URI request to the artifact in the request body.
  - `From`: To the artifact in the URI request from the artifact in the request body.
  - `TwoWay`: The artifacts have a bi-directional trace.
- `IsSuspect`: Marks the trace as suspect.
  Depending on the request, you are adding a trace relationship to, removing a relationship from, or establishing a new child-parent relationship with the artifact in the request body. In each context, some parameters are mandatory, while others are optional or ignored:
- Adding a Trace:
  - Required: `direction`, `type` (set to Manual), one of `artifactId` or `subArtifactId` (the other is optional)
  - Optional: `projectId` and `isSuspect`
- Deleting a Trace:
  - Required: `type` (set to Manual), one of `artifactId` or `subArtifactId` (the other is optional), `direction` (if the query is using the `reconcileWithTwoWay` parameter, which is set to true)
  - Optional: `projectId`
  - Ignored: `isSuspect`
- Changing a Parent Trace:
  - Required: `type` (set to Parent), one of `artifactId` or `projectId`

:::hint{type="info"}
The artifact in the request body must belong to the same project as the artifact in the URI request.
:::

- Ignored: All other properties are ignored.

# Examples

## AddTrace Example

Here is an example of a request body in XML format:

```xml
<?xml version="1.0" ?>			<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">  <Trace>    <ArtifactId>888020</ArtifactId>    <Direction>To</Direction>    <IsSuspect>false</IsSuspect>    <ProjectId>847739</ProjectId>    <Type>Manual</Type>  </Trace></Traces>
```

Here is an example of a request body in JSON format:

```json
[  {    "Type": "Manual",    "ProjectId": 123456,    "ArtifactId": 123,    "IsSuspect": false  },  {    "Type": "Manual",    "ProjectId": 123456,    "ArtifactId": 456,    "IsSuspect": false  },  {    "Type": "Manual",    "ProjectId": 789,    "ArtifactId": 789,    "SubArtifactId": 789,    "IsSuspect": false  }]
```

## Delete Traces Example

Here is an example of a request body in XML format:

```xml
<?xml version="1.0" ?>			<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">  <Trace>    <ArtifactId>843925</ArtifactId>    <Type>Manual</Type>  </Trace></Traces>
```

Here is an example of a request body in JSON format:

```json
[  {    "Type": "Manual",    "ArtifactId": 847750  }]
```

## ChangeParentTrace Example

Here is an example of a request body in XML format:

```xml
<?xml version="1.0" ?>			<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">  <Trace>    <ArtifactId>999666</ArtifactId>    <Type>Parent</Type>  </Trace></Traces>
```

Here is an example of a request body in JSON format:

```json
[  {    "Type": "Parent",    "ArtifactId": 999666  }]
```