---
title: REST API - Add Artifact Request
slug: rm/rest-api-add-artifact-request
docTags: 
createdAt: 2026-06-09T13:38:46.169Z
---

```bash
api/v1/projects/{projectId}/artifacts
```

# Description

Adds a single artifact to the specified project.

# URL Structure

```bash
[Blueprint_URI]/api/v1/projects/{projectId}/artifacts
```

- `ProjectId`: The ID of the project that you want to add the artifact to.

# Supported Methods

- [POST](docId\:Hsi_LzXS8g_RX_ydUdZKg)

# Request Body

The new artifact must be defined in the body of the request. Read more about [REST API - Defining an Artifact in the Request Body](docId\:hcShZB757U-AfE9zrglzp).

# 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)
- 401 (Unauthorized)
  - The user does not have edit permissions for the artifact.
- 404 (Not Found)
  - Artifact not found in the project.
  - Artifact type not found.
- 410 (Invalid Value)
  This error can occur for a variety of reasons, such as:
  - Some of artifact properties have invalid values. (The error is on the artifact level if any artifact properties have errors.)
  - No properties are specified to be updated.
  - The property value cannot be empty.
  - Custom value and choices cannot be specified simultaneously.
  - Property does not support custom values.
  - Only single choice is allowed.
  - Specified choice value does not exist.
  - Value must be less than the maximum value.
  - Value must be greater than the minimum value.
  - Limited count of decimal places.
  - Invalid rich text property value.
  - Specified user or group does not exist.
- 416 (Cannot Update Read-Only Property)
  - Read-only property cannot be changed.
  - ID Property cannot be updated.
- 417 (Invalid Artifact Property Type)
  - Unsupported artifact property type.
  - Property not found.
  - The property type has been removed.
  - Image property update is not supported.
- 420 (Incorrect Folder Structure)
  - Only the project or another folder can be the parent for the folder 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

**Request URI**

```bash
https://production.blueprintcloud.com/api/v1/projects/222996/artifacts
```

**Request Body**

```rust
<?xml version="1.0" ?> <Artifact xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">  <ArtifactTypeId>25</ArtifactTypeId>  <Name>New Textual Requirement</Name>  <ParentId>10</ParentId>  <Properties>    <Property>      <PropertyTypeId>235658</PropertyTypeId>      <TextOrChoiceValue>Sample Description</TextOrChoiceValue>    </Property>    <Property>      <NumberValue>15</NumberValue>      <PropertyTypeId>235659</PropertyTypeId>    </Property>  </Properties></Artifact>
```

**Response Body**

```xml
<?xml version="1.0" ?>
<Artifact xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">
    <AreAttachmentsReadOnly>true</AreAttachmentsReadOnly>
    <AreDocumentReferencesReadOnly>true</AreDocumentReferencesReadOnly>
    <AreTracesReadOnly>true</AreTracesReadOnly>
    <ArtifactTypeId>317929</ArtifactTypeId>
    <ArtifactTypeName>ReUse_TReq</ArtifactTypeName>
    <Attachments>
        <Attachment>
            <FileName>EditReservations.txt</FileName>
            <Id>103542</Id>
            <IsReadOnly>true</IsReadOnly>
            <Link>http://production.blueprintcloud.com/api/v1/projects/4405707/artifacts/4405715/attachments/103542</Link>
        </Attachment>
    </Attachments>
    <BaseArtifactType>TextualRequirement</BaseArtifactType>
    <BlueprintUrl>http://production.blueprintcloud.com?ArtifactId=4405715</BlueprintUrl>
    <Comments>
        <Comment>
            <Author>
                <DisplayName>Default Instance Admin</DisplayName>
                <Id>1</Id>
            </Author>
            <Description>&lt;html&gt;&lt;head&gt;&lt;style type="text/css"&gt;.c0 { padding: 1px 0px 0px; font-size: 11px } .c1 { font-size: 11px } .c2 { margin: 0px; font-size: 11px } &lt;/style&gt;&lt;/head&gt;&lt;body class="c0"&gt;&lt;div class="c1"&gt;&lt;p class="c2"&gt;&lt;span class="c1"&gt;Please review.&lt;/span&gt;&lt;/p&gt;&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;</Description>
            <Id>53978</Id>
            <LastModified>2014-12-22T19:49:31.8270000Z</LastModified>
            <Version>2</Version>
            <IsClosed>false</IsClosed>
            <Status>Open</Status>
        </Comment>
    </Comments>
    <Id>4405715</Id>
    <Name>Edit Reservations</Name>
    <ParentId>4405707</ParentId>
    <ProjectId>4405707</ProjectId>
    <Properties>
        <Property>
            <BasePropertyType>Text</BasePropertyType>
            <IsReadOnly>true</IsReadOnly>
            <IsRichText>false</IsRichText>
            <Name>ID</Name>
            <PropertyTypeId>304155</PropertyTypeId>
            <TextOrChoiceValue>TR_RU4405715</TextOrChoiceValue>
        </Property>
        <Property>
            <BasePropertyType>Text</BasePropertyType>
            <IsRichText>false</IsRichText>
            <Name>Name</Name>
            <PropertyTypeId>304156</PropertyTypeId>
            <TextOrChoiceValue>Edit Reservations</TextOrChoiceValue>
        </Property>
        <Property>
            <BasePropertyType>Text</BasePropertyType>
            <IsRichText>true</IsRichText>
            <Name>Description</Name>
            <PropertyTypeId>304157</PropertyTypeId>
            <TextOrChoiceValue>&lt;html&gt;&lt;head&gt;&lt;style type="text/css"&gt;.c0 { padding: 1px 0px 0px; font-size: 10.6700000762939px } .c1 { font-size: 10.6700000762939px } .c2 { margin: 0px; font-size: 10.6700000762939px } .c3 { font-size: 10.6700000762939px; line-height: 1.45000004768372 } &lt;/style&gt;&lt;/head&gt;&lt;body class="c0"&gt;&lt;div class="c1"&gt;&lt;p class="c2"&gt;&lt;span class="c3"&gt;&lt;span class="c1"&gt;BP Air needs to allow customers to edit their reservations online.&lt;/span&gt;&lt;/span&gt;&lt;/p&gt;&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;</TextOrChoiceValue>
        </Property>
        <Property>
            <BasePropertyType>User</BasePropertyType>
            <Name>ApprovedBy</Name>
            <PropertyTypeId>304320</PropertyTypeId>
            <UsersAndGroups />
        </Property>
        <Property>
            <BasePropertyType>Choice</BasePropertyType>
            <Choices />
            <Name>ItemType</Name>
            <PropertyTypeId>304323</PropertyTypeId>
        </Property>
        <Property>
            <BasePropertyType>User</BasePropertyType>
            <IsReadOnly>true</IsReadOnly>
            <Name>Created By</Name>
            <PropertyTypeId>304195</PropertyTypeId>
            <UsersAndGroups>
                <UserGroup i:type="User">
                    <DisplayName>Default Instance Admin</DisplayName>
                    <Id>1</Id>
                </UserGroup>
            </UsersAndGroups>
        </Property>
        <Property>
            <BasePropertyType>Date</BasePropertyType>
            <DateValue>2014-12-22T19:39:30.0500000Z</DateValue>
            <IsReadOnly>true</IsReadOnly>
            <Name>Created On</Name>
            <PropertyTypeId>304196</PropertyTypeId>
        </Property>
        <Property>
            <BasePropertyType>User</BasePropertyType>
            <IsReadOnly>true</IsReadOnly>
            <Name>Last Edited By</Name>
            <PropertyTypeId>304197</PropertyTypeId>
            <UsersAndGroups>
                <UserGroup i:type="User">
                    <DisplayName>Default Instance Admin</DisplayName>
                    <Id>1</Id>
                </UserGroup>
            </UsersAndGroups>
        </Property>
        <Property>
            <BasePropertyType>Date</BasePropertyType>
            <DateValue>2014-12-22T19:40:01.7970000Z</DateValue>
            <IsReadOnly>true</IsReadOnly>
            <Name>Last Edited On</Name>
            <PropertyTypeId>304198</PropertyTypeId>
        </Property>
    </Properties>
    <Traces>
        <Trace>
            <ArtifactId>4405707</ArtifactId>
            <ArtifactPropertyName>BP Airways 3.0</ArtifactPropertyName>
            <BlueprintUrl>http://production.blueprintcloud.com?ArtifactId=4405707</BlueprintUrl>
            <Direction>From</Direction>
            <IsSuspect>false</IsSuspect>
            <Label>4405707: BP Airways 3.0</Label>
            <Link>http://production.blueprintcloud.com/api/v1/projects/4405707</Link>
            <ProjectId>4405707</ProjectId>
            <Type>Parent</Type>
        </Trace>
        <Trace>
            <ArtifactId>4405714</ArtifactId>
            <ArtifactPropertyName>Reserve Online</ArtifactPropertyName>
            <BlueprintUrl>http://production.blueprintcloud.com?ArtifactId=4405714</BlueprintUrl>
            <Direction>From</Direction>
            <IsSuspect>true</IsSuspect>
            <Label>4405714: Reserve Online</Label>
            <Link>http://production.blueprintcloud.com/api/v1/projects/4405707/artifacts/4405714</Link>
            <ProjectId>4405707</ProjectId>
            <Type>Reuse</Type>
        </Trace>
    </Traces>
    <Version>2</Version>
</Artifact>
```

## JSON Example

**Request URI**

```bash
https://production.blueprintcloud.com/api/v1/projects/222996/artifacts
```

**Request Body**

```rust
{  "Name": "New Textual Requirement",  "ParentId": 10,  "ArtifactTypeId": 25,  "Properties": [    {      "PropertyTypeId": 235658,      "TextOrChoiceValue": "Sample Description"    },    {      "PropertyTypeId": 235659,      "NumberValue": 15.0    }  ]}
```

**Response Body**

```swift
{
    "Id": 4405715,
    "Name": "Edit Reservations",
    "ProjectId": 4405707,
    "Version": 2,
    "ParentId": 4405707,
    "BlueprintUrl": "http://production.blueprintcloud.com?ArtifactId=4405715",
    "ArtifactTypeId": 317929,
    "ArtifactTypeName": "ReUse_TReq",
    "BaseArtifactType": "TextualRequirement",
    "AreTracesReadOnly": true,
    "AreAttachmentsReadOnly": true,
    "AreDocumentReferencesReadOnly": true,
    "Properties": [
        {
            "PropertyTypeId": 304155,
            "Name": "ID",
            "BasePropertyType": "Text",
            "TextOrChoiceValue": "TR_RU4405715",
            "IsRichText": false,
            "IsReadOnly": true
        },
        {
            "PropertyTypeId": 304156,
            "Name": "Name",
            "BasePropertyType": "Text",
            "TextOrChoiceValue": "Edit Reservations",
            "IsRichText": false
        },
        {
            "PropertyTypeId": 304157,
            "Name": "Description",
            "BasePropertyType": "Text",
            "TextOrChoiceValue": "<html><head><style type=\"text/css\">.c0 { padding: 1px 0px 0px; font-size: 10.6700000762939px } .c1 { font-size: 10.6700000762939px } .c2 { margin: 0px; font-size: 10.6700000762939px } .c3 { font-size: 10.6700000762939px; line-height: 1.45000004768372 } </style></head><body class=\"c0\"><div class=\"c1\"><p class=\"c2\"><span class=\"c3\"><span class=\"c1\">BP Air needs to allow customers to edit their reservations online.</span></span></p></div></body></html>",
            "IsRichText": true
        },
        {
            "PropertyTypeId": 304320,
            "Name": "ApprovedBy",
            "BasePropertyType": "User",
            "UsersAndGroups": []
        },
        {
            "PropertyTypeId": 304323,
            "Name": "ItemType",
            "BasePropertyType": "Choice",
            "Choices": []
        },
        {
            "PropertyTypeId": 304195,
            "Name": "Created By",
            "BasePropertyType": "User",
            "UsersAndGroups": [
                {
                    "Type": "User",
                    "Id": 1,
                    "DisplayName": "Default Instance Admin"
                }
            ],
            "IsReadOnly": true
        },
        {
            "DateValue": "2014-12-22T19:39:30.0500000Z",
            "PropertyTypeId": 304196,
            "Name": "Created On",
            "BasePropertyType": "Date",
            "IsReadOnly": true
        },
        {
            "PropertyTypeId": 304197,
            "Name": "Last Edited By",
            "BasePropertyType": "User",
            "UsersAndGroups": [
                {
                    "Type": "User",
                    "Id": 1,
                    "DisplayName": "Default Instance Admin"
                }
            ],
            "IsReadOnly": true
        },
        {
            "DateValue": "2014-12-22T19:40:01.7970000Z",
            "PropertyTypeId": 304198,
            "Name": "Last Edited On",
            "BasePropertyType": "Date",
            "IsReadOnly": true
        }
    ],
    "Comments": [
        {
            "LastModified": "2014-12-22T19:49:31.8270000Z",
            "IsClosed": false,
            "Status": "Open",
            "Id": 53978,
            "Author": {
                "Type": "User",
                "Id": 1,
                "DisplayName": "Default Instance Admin"
            },
            "Version": 2,
            "Description": "<html><head><style type=\"text/css\">.c0 { padding: 1px 0px 0px; font-size: 11px } .c1 { font-size: 11px } .c2 { margin: 0px; font-size: 11px } </style></head><body class=\"c0\"><div class=\"c1\"><p class=\"c2\"><span class=\"c1\">Please review.</span></p></div></body></html>"
        }
    ],
    "Traces": [
        {
            "Type": "Parent",
            "Direction": "From",
            "ProjectId": 4405707,
            "ArtifactId": 4405707,
            "ArtifactPropertyName": "BP Airways 3.0",
            "Label": "4405707: BP Airways 3.0",
            "BlueprintUrl": "http://production.blueprintcloud.com?ArtifactId=4405707",
            "Link": "http://production.blueprintcloud.com/api/v1/projects/4405707",
            "IsSuspect": false
        },
        {
            "Type": "Reuse",
            "Direction": "From",
            "ProjectId": 4405707,
            "ArtifactId": 4405714,
            "ArtifactPropertyName": "Reserve Online",
            "Label": "4405714: Reserve Online",
            "BlueprintUrl": "http://production.blueprintcloud.com?ArtifactId=4405714",
            "Link": "http://production.blueprintcloud.com/api/v1/projects/4405707/artifacts/4405714",
            "IsSuspect": true
        }
    ],
    "Attachments": [
        {
            "Id": 103542,
            "FileName": "EditReservations.txt",
            "Link": "http://production.blueprintcloud.com/api/v1/projects/4405707/artifacts/4405715/attachments/103542",
            "IsReadOnly": true
        }
    ]
}
```