---
title: "Polarity Server v5 Annotations REST API Reference"
slug: "polarity-rest-api-annotations"
description: "Learn how to create, read, update, and delete annotations (tags, notes, labels) in Polarity Server v5 via REST API endpoints. Complete API reference with examples for programmatic annotation management and integration."
updated: 2025-07-13T00:55:20Z
published: 2025-07-13T00:55:20Z
---

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

# Annotations

In Polarity, an annotation is made up of an entity and a tag. Within the REST API, tags and annotations are synonymous. An entity can be any value you want to add an annotation/tag to. For example, you might have the entity `127.0.0.1` and apply the annotation “localhost” to it.

Every annotation/tag has an `id` and every entity has an `id`. When an annotation is applied to an entity that creates a tag-entity pair which has it’s own `id` as well.

## Updating Annotations

To update an annotation you need to know the tag-entity `id` that the annotation is a part of. You must then send a `POST` request to the `/api/tags` endpoint and target the tag-entity pair as a relationship.

curlPython

```bash
curl -v -X POST \
'https://<polarity.server.url>/api/tags' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
--data-binary @- <<EOF
{
    "data": {
        "attributes": {
            "tag-name": "<UPDATED_ANNOTATION_VALUE>"
        },
        "relationships": {
            "tag-entity-pairs": {
                "data": [
                    {
                        "type": "tag-entity-pairs",
                        "id": "<TAG_ENTITY_PAIR_ID>"
                    }
                ]
            }
        },
        "type": "tags"
    }
}
EOF
```

```python
import requests
import json

def update_annotation(token, host, new_annotation, tag_entity_pair_id):
    url = f'{host}/api/tags'
    payload = json.dumps({
        'data': {
            'attributes': {
                'tag-name': new_annotation
            },
            'relationships': {
                'tag-entity-pairs': {
                    'data': [
                        {
                            'type': 'tag-entity-pairs',
                            'id': tag_entity_pair_id
                        }
                    ]
                }
            },
            'type': 'tags'
        }
    })

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.post(url, headers=headers, data=payload)
    response.raise_for_status()

    return response.json()

# Update annotation for the tag-entity paid 50 to the value "updated annotation"
new_annotation = 'updated annotation'
tag_entity_pair_id = '50'
unsubscribe_result = update_annotation(token, HOST, new_annotation, tag_entity_pair_id)
```

## Deleting Annotations

To delete an annotation you just need to know the tag-entity pair id that you wish to remove. Deleting this `id` removes the relationship between a specific tag (annotation) and entity. Once you know the tag-entity pair id, you can send a `DELETE` request to the `/api/tag-entity-pairs/&lt;TAG_ENTITY_PAID_ID&gt;` endpoint. See examples below:

curlPython

```bash
curl -v -X DELETE \
https://<polarity.server.url>/api/tag-entity-pairs/<TAG_ENTITY_PAIR_ID> \
--header 'Authorization: Bearer <AUTH_TOKEN>'
```

```python
def delete_annotation(token, host, tag_entity_paid_id):
    url = f'{host}/api/tag-entity-pairs/{tag_entity_paid_id}'
     
    headers = {
        #'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.delete(url, headers=headers, verify=False)
    response.raise_for_status()

    return response.json()
```

## Finding a Tag-Entity Pair ID

If you are attempting to update a single annotation and need to know the `id` of the tag-entity pair, you can find this via your browser and the “Explore Annotations” page. Navigate to the annotation of interest and then click on the annotation in the UI:

Check the URL in the browser and look for the numeric value after the term “comments”. This numeric value is the tag-entity pair id. As an example, the URL will look like this:

```plaintext
https://<POLARITY_SERVER>/explore/entity/<ENTITY_ID>/comments/<TAG_ENTITY_PAIR_ID>?option%5BsearchComments%5D=false&option%5BsearchTags%5D=false
```

If you are searching for the annotation via the `parse-entities` endpoint, the `tag-entity` id is the `id` value under the `contexts` array.

See [searching annotations](/v1/docs/searching-polarity-integrations#annotations) for more information on how to get the tag-entity pair id.