---
title: Subscription-API
slug: editorial/subscription-api
description: Subscription-API
docTags: 
createdAt: 2023-08-17T12:36:27.632Z
---

With the Catalog Subscription API, developers get access to a stream of events related to and app or team.

:::hint{type="info"}
This documentation is intended for technical users (integrators and developers). 
:::

:::hint{type="info"}
This documentation assumes familiarity with GraphQL. Please read the official website's [Introduction to GraphQL](https://graphql.org/learn/) to learn about the concepts if you have never worked with GraphQL before.
:::

# Introduction

## What are Events?

When working with the Purple DS Content Cloud all actions related to content are processed by an event streaming platform. When an editor publishes a new article or and updated revision of an article, this change gets processed by our Content Pipeline and eventually lands in the database used by clients to access the contents.

## What is the Subscription API?

The Subscription API is a backend service that implements GraphQL subscriptions specification. With it you can start a WebSocket connection to our backend service and get real-time delivery of Content Pipeline events.

After subscribing to events your GraphQL client will receive all events matching the query. If the WebSocket connection between the backend and client is interrupted you will receive all events queued since the last subscription. The state is stored based on the following query parameters:

**AppInfo**

- appId
- preview

**DeviceInfo**

- deviceId
- platform

**Authorization**

- accessToken
- accountAccessToken
- subscriptionCodes

**Specific parameters**

- postId
- publicationId
- contentFilter

 If any of the above mentioned parameters changes, a new subscription is created.

:::hint{type="warning"}
The state of your subscription is kept for 7 days. After that all state is deleted and resubscription will lead to only new events being delivered.
:::

:::hint{type="info"}
The Subscription API has a latency of up to 400ms. This means that there might be a lag of 400ms between an article being available in the Catalog API ("published") and the article being delivered as an event through our Subscription API.
:::

# Usage

## Connection

The API endpoint is available at [wss://catalog.purplemanager.com/subscriptions/subscriptions ](wss://catalog.purplemanager.com/subscriptions/subscriptions)(Secure WebSocket connection)

A web-based schema exploration and query sandbox is available at [https://catalog.purplemanager.com/subscriptions/graphiql](https://catalog.purplemanager.com/subscriptions/graphiql)

# Changelog

## Release 2025-05-12

### 📘 Taxonomy Update Behavior Change

**Overview**

Previously, any update to taxonomy data (e.g. renaming a category or reorganizing the structure) triggered **content changed events** for all affected content items. In large catalogs, this behavior could result in **millions of events**, overwhelming downstream systems and degrading performance.

**What's New**

Starting with this update, **taxonomy changes no longer trigger content changed events**. Instead, taxonomy updates emit a single, dedicated event:

- **PublishedTaxonomyEvent** for changes and initial creation
- **DeletedTaxonomyEvent** for deletions

This change significantly reduces the volume of events and provides a more efficient way to propagate taxonomy updates.

**Required Action for Integrators**

If you are using the **Catalog Subscription API**, and your application relies on detecting taxonomy changes to maintain data consistency, you must:

- Subscribe to **PublishedTaxonomyEvent** via the **changes** subscription type.
- Handle taxonomy updates by consuming the data provided in the taxonomy event and updating your local database or cache accordingly.

Example:

Previously, when a taxonomy was changed, you would get an updated post via **postUpdates** or **publicationUpdates**. Now, you will need to start subscribing to **changes** and handle **PublishedTaxonomyEvent **and **DeletedTaxonomyEvent** events.

**Benefits**

- Improved system scalability and reduced noise in event-driven architectures.
- Clear separation between content and taxonomy change notifications.