---
title: "Subscribe devices to a topic"
description: "Subscribe devices to one of your app's topics, server-side.\n\nUse this when your backend decides membership (a plan, a cohort, a segment)\nrather than the device deciding for itself — a client can subscribe itself\nthrough the Firebase SDK without involving Truememory at all.\n\nThe topic is namespaced to your app before it reaches FCM, and the response\nechoes the qualified name. **Truememory does not store subscriptions**: FCM\nowns that state and offers no way to read it back, so a local copy would\ndrift. Keep your own record if you need to enumerate membership."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: AI Gateway API › Notifications

`POST /notifications/topics/{topic}/subscribe`

Subscribe devices to one of your app's topics, server-side.

Use this when your backend decides membership (a plan, a cohort, a segment)
rather than the device deciding for itself — a client can subscribe itself
through the Firebase SDK without involving Truememory at all.

The topic is namespaced to your app before it reaches FCM, and the response
echoes the qualified name. **Truememory does not store subscriptions**: FCM
owns that state and offers no way to read it back, so a local copy would
drift. Keep your own record if you need to enumerate membership.

## Authentication

- `HTTPBearer`, http, header `Authorization`

## Path parameters

- `topic` (`subscribe_to_topic.path.topic`; string, required) — Topic name, unprefixed.
  - maxLength 900; pattern `^[a-zA-Z0-9\-_.~%]+$`

## Header parameters

- `X-App-Id` (`subscribe_to_topic.header.X-App-Id`; any of, optional)
  - any of: `string`, `null`
- `X-On-Behalf-Of` (`subscribe_to_topic.header.X-On-Behalf-Of`; any of, optional)
  - any of: `string`, `null`
- `X-External-User-Id` (`subscribe_to_topic.header.X-External-User-Id`; any of, optional)
  - any of: `string`, `null`

## Request body

_Required._

- `user_ids` (`subscribe_to_topic.user_ids`; any of, optional) — Truememory user ids; resolved to registered devices for the calling app.
  - any of: `array<string>`, `null`
- `tokens` (`subscribe_to_topic.tokens`; any of, optional) — Raw FCM registration tokens.
  - any of: `array<string>`, `null`

## Example request

```json
{
  "user_ids": [
    "string"
  ],
  "tokens": [
    "string"
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://truememory-api.mvstg.com/notifications/topics/<topic>/subscribe' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_ids": [
    "string"
  ],
  "tokens": [
    "string"
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://truememory-api.mvstg.com/notifications/topics/<topic>/subscribe';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({user_ids: ['string'], tokens: ['string']})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://truememory-api.mvstg.com/notifications/topics/<topic>/subscribe"

payload = {
    "user_ids": ["string"],
    "tokens": ["string"]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "topic": "string",
  "success_count": 0,
  "failure_count": 0,
  "results": [
    {
      "target": "string",
      "user_id": "string",
      "success": true,
      "message_id": "string",
      "error_code": "string",
      "error": "string",
      "pruned": false
    }
  ],
  "unreachable_user_ids": [
    "string"
  ],
  "pruned_token_count": 0
}
```

- `topic` (`subscribe_to_topic.response.200.topic`; string, required) — The app-namespaced topic FCM was given.
- `success_count` (`subscribe_to_topic.response.200.success_count`; integer, required)
- `failure_count` (`subscribe_to_topic.response.200.failure_count`; integer, required)
- `results` (`subscribe_to_topic.response.200.results`; array<object>, required)
  - `target` (`subscribe_to_topic.response.200.results.target`; string, required) — The registration token, topic, or condition sent to.
  - `success` (`subscribe_to_topic.response.200.results.success`; boolean, required)
  - `user_id` (`subscribe_to_topic.response.200.results.user_id`; any of, optional) — Set when the target was resolved from the device registry.
    - any of: `string`, `null`
  - `message_id` (`subscribe_to_topic.response.200.results.message_id`; any of, optional)
    - any of: `string`, `null`
  - `error_code` (`subscribe_to_topic.response.200.results.error_code`; any of, optional) — FCM's error code, uppercased.
    - any of: `string`, `null`
  - `error` (`subscribe_to_topic.response.200.results.error`; any of, optional)
    - any of: `string`, `null`
  - `pruned` (`subscribe_to_topic.response.200.results.pruned`; boolean, optional) — The token was dropped from the registry because FCM reports it dead.
    - default `false`
- `unreachable_user_ids` (`subscribe_to_topic.response.200.unreachable_user_ids`; array<string>, optional) — Requested users with no device registered for this app.
- `pruned_token_count` (`subscribe_to_topic.response.200.pruned_token_count`; integer, optional)
  - default `0`

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`subscribe_to_topic.response.422.detail`; array<object>, optional)
  - `loc` (`subscribe_to_topic.response.422.detail.loc`; array<any of>, required)
    - any of: `string`, `integer`
  - `msg` (`subscribe_to_topic.response.422.detail.msg`; string, required)
  - `type` (`subscribe_to_topic.response.422.detail.type`; string, required)
  - `input` (`subscribe_to_topic.response.422.detail.input`; unknown, optional)
  - `ctx` (`subscribe_to_topic.response.422.detail.ctx`; object, optional)


Source: https://truememory-docs.mvstg.com/api/notifications/topics/subscribe/index.md