---
title: REST API - Add Traces Request
slug: rm/rest-api-add-traces-request
docTags:
createdAt: 2026-06-09T13:38:46.241Z
---
```bash
api/v1/projects/{projectId}/artifacts/{artifactId}/traces?reconcilewithtwoway={boolean}
```
# Description
Adds trace(s) to the artifact you specify.
You can only add manual traces (that is, a trace manually added by a user). You cannot add parent/child relationships, reuse relationships or other relationships.
:::hint{type="info"}
ou can add more than one trace in a single request as long as the `ArtifactId` you specify in the request body has a trace relationship with the artifact in the request URI.
:::
# URL Structure
```bash
[Blueprint_URI]/api/v1/projects/{ProjectId}/artifacts/{ArtifactId}/traces
```
- `ProjectId`: The ID of the project that contains the artifact you want to add the trace(s) to.
- `ArtifactId`: The ID of the artifact you want add the trace(s) to.
# Supported Methods
- ****[POST](docId\:Hsi_LzXS8g_RX_ydUdZKg)****
# Request URI Parameters
- `ReconcileWithTwoWay` (optional): Indicates how to handle the existence of an inverse trace. This parameter can be set to **true** or **false**. If set to **true**, and an inverse trace already exists, the request does not return an error; instead, the trace **Type** is set to **TwoWay**. The default is **false** if not specified.The default is **true** if the parameter is included in the URI with no given value.
# Request Body Parameters
The trace(s) must be included in the body of the request. Read more about how to specify [one or more traces](docId:5Qd6-FuzDOthy7-MRc1T1) in the request body.
# Blueprint Result Codes
Your response may contain `ResultCode` and `Message` parameters if your request involves changes to Blueprint data. These parameters provide detailed information about the result of your request.
- 201 (Successfully Created)
- 400 (Bad Request)
- 421 (Trace Not Manual)
- Only valid trace value is Manual.
- 424 (Trace Artifact Not Found)
- Artifact for the trace cannot be located.
- 425 (Trace Cannot Be Managed)
- In order to manage a trace, you need to have Trace permissions for both traced artifacts and Edit permissions for at least one artifact.
- 426 (Traced Sub-Artifact Does Not Belong To Provided Artifact)
- Sub-artifact does not belong to the provided artifact.
- 500 (Error)
- A system error has occurred.
# HTTP Status Codes
- 200: OK
- 201: Successfully Created
- 206: Partial Content
- 400: Bad Request
This error can occur for a variety of reasons:
- At least one URI or request body parameter is invalid, such as one of the [Filter](docId\:Sv9GjVErxCZcgqdn28J7U), Traces, Offset or Limit parameters.
- A required value has not been provided.
- If you are submitting a [POST](docId\:Hsi_LzXS8g_RX_ydUdZKg) or [PATCH](docId\:RcjvHRLbY6de-zGKeHxuI) request and have not added the `X-HTTP-Method-Override` parameter to your request header.
- 401: Unauthorized
- The Blueprint token is missing, invalid or expired.
- 403: Forbidden
- The applicable permissions are needed. For example, this error can occur when:
- An Author or Collaborate license is needed for access.
- Comment permissions are needed on the artifact.
- Edit permissions are needed on the change summary job.
- 404: NotFound
- Item is not found in the project. For example, this error can occur when:
- Artifact not found.
- Artifact type not found.
- Project not found.
- ALM target not found.
- Change summary job not found.
- User does not have edit permissions for this artifact, project or ALM target.
- 409: Conflict
- Reason for failure can be found in the response body. Additional information may also be found in the log.
- 411: Length Required
- If the Content-Length header is missing in the request.
- 413: Request Entity Too Large
- If the provided file size is larger than allowed.
- 415: Unsupported Media Type
- If the provided media type is not of MIME Multipart Content "form-data."
- 416: Request Range Not Satisfiable
- If `offset `points to a part of a collection that is not available.
- 500: Internal Server Error
- 501: Not Implemented
# Examples
## XML Example
**Example 1: successful add trace call from artifact 777001 to 888020**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/777001/traces
```
**Request Body**
```xml
888020 To false 847739 Manual
```
**Response Body**
```xml
888020 To false Trace between 777001 and 888020 added successfully. 847739 201 Manual
```
**Example 2: failed attempt to add inverse trace from artifact 888020 to 777001**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/888020/traces
```
**Request Body**
```xml
777001 To false 847739 Manual
```
**Response Body**
```xml
777001 To false A trace with the specified artifact/subartifact already exists. Provided values are Project Id: 847739, Artifact Id: 777001, Subartifact Id: 0 847739 400 Manual
```
**Example 3: using the** `ReconcileWithTwoWay` **parameter to handle an existing trace relationship**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/888020/traces?reconcilewithtwoway=true
```
**Request Body**
```xml
777001 To false 847739 Manual
```
**Response Body**
```xml
777001 TwoWay false Trace between 777001 and 888020 added successfully. 847739 201 Manual
```
## JSON Example
**Example 1: successful add trace call from artifact 777001 to 888020**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/777001/traces
```
**Request Body**
```json
[ { "Type": "Manual", "ProjectId": 847739, "ArtifactId": 888020, "Direction": "To", "IsSuspect": false }]
```
**Response Body**
```json
[ { "ProjectId": 847739, "ArtifactId": 888020, "Direction": "To", "Type": "Manual", "Message": "Trace between 777001 and 888020 added successfully.", "ResultCode": 201, "IsSuspect": false }]
```
**Example 2: failed attempt to add inverse trace from artifact 888020 to 777001**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/888020/traces
```
**Request Body**
```json
[ { "Type": "Manual", "ProjectId": 847739, "ArtifactId": 777001, "Direction": "To", "IsSuspect": false }]
```
**Response Body**
```json
[ { "ProjectId": 847739, "ArtifactId": 777001, "Direction": "To", "Type": "Manual", "Message": "A trace with the specified artifact/subartifact already exists. Provided values are Project Id: 847739, Artifact Id: 777001, Subartifact Id: 0", "ResultCode": 400, "IsSuspect": false }]
```
**Example 3: using the ReconcileWithTwoWay parameter to handle an existing trace relationship**
**Request URI**
```bash
https://blueprintcloud.com/api/v1/projects/847739/artifacts/888020/traces?reconcilewithtwoway=true
```
**Request Body**
```json
[ { "Type": "Manual", "ProjectId": 847739, "ArtifactId": 777001, "Direction": "To", "IsSuspect": false }]
```
**Response Body**
```json
[ { "ProjectId": 847739, "ArtifactId": 777001, "Direction": "TwoWay", "Type": "Manual", "Message": "Trace between 777001 and 888020 added successfully.", "ResultCode": 201, "IsSuspect": false }]
```