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

# Subscriptions Overview

> Real-time updates via WebSocket

The GraphQL API supports real-time subscriptions for content updates via WebSocket connections.

## Subscription Schema

```graphql theme={null}
type Subscription {
  # Subscribe to updates for a specific content item
  contentUpdated(id: ID!): ContentUpdate!

  # Preview link updates (token-based auth)
  previewUpdated(token: String!): PreviewUpdate!
}
```

## Available Subscriptions

<CardGroup cols={2}>
  <Card title="contentUpdated" icon="rotate" href="/graphql/subscriptions/content-updated">
    Watch for updates to published content
  </Card>

  <Card title="previewUpdated" icon="eye" href="/graphql/subscriptions/preview-updated">
    Watch for updates to draft previews
  </Card>
</CardGroup>

## WebSocket Client Setup

### Using graphql-ws

```javascript theme={null}
import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'wss://api.metabind.ai/graphql',
  connectionParams: {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
});
```

### For Preview Subscriptions

Use `previewToken` instead of `x-api-key`:

```javascript theme={null}
const client = createClient({
  url: 'wss://api.metabind.ai/graphql',
  connectionParams: {
    previewToken: 'YOUR_PREVIEW_TOKEN'
  }
});
```

## Handling Large Payloads

AWS WebSocket has a 100KB payload limit. When data exceeds this limit:

1. The `content` or `component` field will be `null`
2. The `resolvedRef` field is always included
3. Fetch the full data separately using the ID
4. Use the `resolvedRef` to fetch package data

```javascript theme={null}
if (!update.content) {
  // Content exceeded 100KB - fetch separately
  const content = await fetchContent(update.contentId);
  refreshContent(content, update.resolvedRef);
} else {
  // Content included in payload
  refreshContent(update.content, update.resolvedRef);
}
```

## Related

* [Subscription Types](/graphql/types/subscription-types) - ContentUpdate, PreviewUpdate type definitions
* [Caching](/graphql/caching) - Normalized package caching for subscriptions