> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deleting from Qbilon

> Use the deletion API to remove assets, relations, and properties.

## Preface

Qbilon provides a deletion API that allows you to precisely delete asset data from Qbilon.

The deletion API can delete data from Qbilon using explicit IDs, targeting either entire assets or only specific properties of assets. For this purpose, the data endpoint `/apiv1/data/delete/{taskId}` allows `POST` requests to be received.

To use the deletion endpoint, two conditions must be met:

* a prepared data source (see section [REST API](https://doc.qbilon.io/12-customizing-qbilon/rest-api/index)) in whose name deletion requests are sent to Qbilon (this is the `{taskId}` part in the URL), and
* compliance with the data format as defined in Qbilon's OpenAPI specification (navigate to `Documentation → API Documentation` or enter the URL `<myhost>/openapi/index.html`).

## Data Format

The Qbilon Deletion API supports complete and partial deletion of assets and relations in your Qbilon instance. It uses a simple format in JSON that can be included in the body of a POST request to delete data from Qbilon. The body consists of some optional parts and some mandatory parts. This allows a user to delete exactly as much information as desired.

### Full-Fledged Deletion Format

A full-fledged example of the format for a body deleting different assets/relations either fully or partially from Qbilon could look like this:

```json theme={null}
{
  "typeElements": [
    {
      "externalId": "SP1"
    },
    {
      "externalId": "SP2",
      "properties": [
        "Last Seen",
        "Name"
      ]
    },
    {
      "qbilonId": "__________F"
    },
    {
      "qbilonId": "__________F",
      "properties": [
        "Name"
      ]
    }
  ],
  "relationElements": [
    {
      "externalId": "some-edge-1"
    },
    {
      "externalId": "some-edge-2",
      "properties": [
        "Name"
      ]
    },
    {
      "qbilonId": "__________E"
    },
    {
      "qbilonId": "__________F",
      "properties": [
        "Name"
      ]
    }
  ]
}
```

### Deleting an Asset/Relation

For each asset that you want to delete, you first have to provide information about whether it is an asset or a relation. This is done by providing the corresponding ID in either the `typeElements` or `relationElements` array. For each asset to be deleted, you have to provide an object in the array consisting of either an `externalId` , i.e., an ID that was used within the data source given in the URL, or a global `qbilonId`. If both are given, the `qbilonId` takes precedence, with no fallback to the `externalId` if the `qbilonId` is not found.

In order to delete the whole asset or relation, the object provided in the array must not have a `properties` field, but only `externalId` and/or `qbilonId`, as shown in the following example.

```json theme={null}
{
  "typeElements": [
    { "externalId": "SP1" },
    { "qbilonId": "__________F" }
  ],
  "relationElements": [
    { "externalId": "some-edge-1" },
    { "qbilonId": "__________E" }
  ]
}
```

> [!NOTE]
>
> If you delete an asset that has incoming or outgoing relations, those relations are implicitly deleted as well, since there can be no relations without a corresponding source or target asset in Qbilon.

### Deleting an Asset/Relation Property

In order to delete only one or more properties of an asset or relation, you can provide the **optional** `properties` array. Within this array you can provide the names of the properties that should be deleted. If this field is provided, the asset/relation will not be deleted, only the given properties. If none of the given properties are found in the given asset/relation, nothing will happen.

```json theme={null}
{
  "typeElements": [
    {
      "externalId": "SP2",
      "properties": ["Last Seen", "Name"]
    },
    {
      "qbilonId": "__________F",
      "properties": ["Name"]
    }
  ],
  "relationElements": [
    {
      "externalId": "some-edge-2",
      "properties": ["Name"]
    },
    {
      "qbilonId": "__________F",
      "properties": ["Name"]
    }
  ]
}
```

## Deletion Response

Qbilon provides you with a detailed response about what happened during the deletion of the provided assets, relations or their properties.

A valid response for the above deletion request could look like this:

```json theme={null}
{
  "numberOfDeletedNodes": 0,
  "numberOfDeletedEdges": 0,
  "numberOfDeletedNodeProperties": 1,
  "numberOfDeletedEdgeProperties": 0,
  "errors": [
    {
      "qbilonId": "__________E",
      "reason": 404
    },
    {
      "externalId": "SP2",
      "properties": [
        "Last Seen"
      ],
      "reason": 403
    },
    {
      "externalId": "SP1",
      "reason": 404
    },
    {
      "qbilonId": "__________E",
      "reason": 404
    },
    {
      "externalId": "some-edge-2",
      "reason": 404
    },
    {
      "externalId": "some-edge-1",
      "reason": 404
    }
  ]
}
```

Qbilon provides you with a summary of the number of deleted assets/relations and the number of deleted properties for the given assets/relations (only for partial deletions).

Here are some examples:

* If you successfully deleted a single asset, the response would look like this:

```json theme={null}
{
  "numberOfDeletedNodes": 1,
  "numberOfDeletedEdges": 0,
  "numberOfDeletedNodeProperties": 0,
  "numberOfDeletedEdgeProperties": 0
}
```

* If you successfully deleted a single asset and the property of another asset, the response would look like this:

```json theme={null}
{
  "numberOfDeletedNodes": 1,
  "numberOfDeletedEdges": 0,
  "numberOfDeletedNodeProperties": 1,
  "numberOfDeletedEdgeProperties": 0
}
```

* If you successfully deleted a property of one asset, but failed to do the same on another asset (as it doesn't exist):

```json theme={null}
{
  "numberOfDeletedNodes": 0,
  "numberOfDeletedEdges": 0,
  "numberOfDeletedNodeProperties": 1,
  "numberOfDeletedEdgeProperties": 0,
  "errors": [
    {
      "externalId": "my-Id",
      "properties": [
        "Does not Exist"
      ],
      "reason": 404
    }
  ]
}
```

* If you successfully deleted one property of an asset, but failed to delete another because it didn't exist, and another because it was a system property:

```json theme={null}
{
  "numberOfDeletedNodes": 0,
  "numberOfDeletedEdges": 0,
  "numberOfDeletedNodeProperties": 1,
  "numberOfDeletedEdgeProperties": 0,
  "errors": [
    {
      "externalId": "my-Id",
      "properties": [
        "Last Seen"
      ],
      "reason": 403
    },
    {
      "externalId": "my-Id",
      "properties": [
        "Does not exist"
      ],
      "reason": 404
    }
  ]
}
```

## Error Handling

### Format Violations

There are cases that are not handled gracefully by Qbilon, but result in an endpoint call error:

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Invalid `qbilonId` | The provided `qbilonId` is invalid, e.g., "Hello World" instead of a proper ID. | 422 - Unprocessable Entity error. |
| Valid format but non-existent `taskId` | The provided `taskId` is well-formed but does not refer to an existing data source. | 404 - Not Found error. |

### Inconsistent Input

Qbilon will always try to delete as much as possible from your given request, but if something went wrong during deleting an asset/relation or its properties, the response will contain the **optional** `errors` array.

Within this array, there will be explanations for each whole asset/relation and also its properties as to why the deletion couldn't be performed as requested.

The following cases are handled in a graceful manner:

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Valid `qbilonId` but does not exist | The provided `qbilonId` is valid but refers to no existing asset. | Returns an object with the `qbilonId` and reason `404 - Not Found`. |
| Non-existent `externalId` | The provided `externalId` does not refer to an existing asset. | Returns an object with the `externalId` and reason `404 - Not Found`. |
| Attempt to delete a system property | Some properties (e.g., Qbilon ID, Last Seen, First Seen, Datasources) are system-defined and cannot be deleted. | Returns an object with the `qbilonId` or `externalId` and reason `403 - Unauthorized`. |
| Attempt to delete the last property of an asset or relation | Each asset/relation must have at least one property; deleting the last one is not allowed. | Returns an object with the `qbilonId` or `externalId` and reason `403 - Unauthorized`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.