Channels

Updated on 12 Jul 2025
5 Minutes to read

Print
Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Channels are used to group annotations into logical groups.

Subscribing

Subscriptions are modeled as a channel-subscriptions relationship between a user and a channel. To subscribe to a channel you must provide the id of the channel as well as the id of your user account. In the case of an API key, you will need to provide the API keys “Proxy User ID”. See Obtaining API token User ID for more information on how to get the Proxy User ID of an API token.

curl

Python

curl -v -X POST \
'https://<polarity.server.url>/api/channel-subscriptions' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
--data-binary @- <<EOF
{
  "data": [
    {
      "type": "channel-subscriptions",
      "relationships": {
        "channel": {
          "data": {
            "type": "channels",
            "id": "<CHANNEL_ID>"
          }
        },
        "user": {
          "data": {
            "type": "users",
            "id": "<YOUR_USER_ID>"
          }
        }
      }
    }
  ]
}
EOF

import requests
import json

def subscribe_to_channel(token, host, channel_id, user_id):
    url = f'{host}/api/channel-subscriptions'
    payload = json.dumps({
        'data': [
            {
                'type': "channel-subscriptions",
                'relationships': {
                    'channel': {
                        'data': {
                            'type': 'channels',
                            'id': channel_id
                        }
                    },
                    'user': {
                        'data': {
                            'type': 'users',
                            'id': user_id
                        }
                    }
                }
            }
        ]
    })

    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()
  
# Subscribe as Admin (user_id = 1) to the General Channel (channel_id = -1)
general_channel = '-1'
user_id = 1
subscribe_result = subscribe_to_channel(token, HOST, general_channel, user_id)

Unsubscribing

Unsubscribing is done the same way a subscribing except the HTTP operation should be DELETE.

curl

Python

curl -v -X DELETE\
'https://<polarity.server.url>/api/channel-subscriptions' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
--data-binary @- <<EOF
{
  "data": [
    {
      "type": "channel-subscriptions",
      "relationships": {
        "channel": {
          "data": {
            "type": "channels",
            "id": "<CHANNEL_ID>"
          }
        },
        "user": {
          "data": {
            "type": "users",
            "id": "<YOUR_USER_ID>"
          }
        }
      }
    }
  ]
}
EOF

import requests
import json

def unsubscribe_from_channel(token, host, channel_id, user_id):
    url = f'{host}/api/channel-subscriptions'
    payload = json.dumps({
        'data': [
            {
                'type': "channel-subscriptions",
                'relationships': {
                    'channel': {
                        'data': {
                            'type': 'channels',
                            'id': channel_id
                        }
                    },
                    'user': {
                        'data': {
                            'type': 'users',
                            'id': user_id
                        }
                    }
                }
            }
        ]
    })

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

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

    return response.json()
  
# Unsubscribe as Admin (user_id = 1) to the General Channel (channel_id = -1)
general_channel = '-1'
user_id = 1
unsubscribe_result = unsubscribe_from_channel(token, HOST, general_channel, user_id)

Obtaining API Token User ID

If you are using a Polarity API Token generated via the API Token admin page you will need to get the API Token “Proxy User Id” value to be able to subscribe and unsubscribe to channels. The “Proxy User Id” of the API Token can be used anywhere the “User ID” of the API Token is required (e.g., in the channel-subscriptions endpoints).

To obtain the API Token User ID you will first need to navigate to the Details page for your API Token. Go to the “Server Configuration” → “API Keys” page. Find the API key you are using and click on the three dots icon under “Actions”. Select “Edit Details”.

You will now need to open the Inspector in your browser. In most browsers this can be done by right clicking anywhere on the web page and clicking on “Inspect” or “Inspector”. Once the Inspector is open, click on the “Network” tab. Refresh the page and filter the network requests for the term “api-keys”.

Click on the visible request and click on “Preview” to view the response from the server. This response will contain the “Proxy User ID”. To view it, click on “data” → “relationships” → “proxy-user” → “data”. The value of id if the “Proxy User Id” of your API key.

Upcoming Updates
The next release of the Polarity server will improve the workflow around using API keys for subscribing to channels. The “Proxy User Id” value will be displayed directly on the API Key Details page without needing to manually check the server response payload. In addition, for users using their API key to search Annotations, API keys will automatically be subscribed to any channels they are given access to when the API key is created.

Was this article helpful?

What's Next

Annotations

Table of contents

Subscribing
Unsubscribing
Obtaining API Token User ID

Company

Sales and Support