# Notifications

## Overview

The Notifications API provides endpoints for managing push notification settings for users, specifically related to Firebase Cloud Messaging (FCM) tokens.

## Endpoints

### Update User FCM Token

```
POST /api/v1/notifications/user-fcm-token
```

**Description**: Updates or registers the Firebase Cloud Messaging (FCM) token for the authenticated user's device, enabling push notifications.

**Authentication Required**: Yes (Requires Privy Session and Profile)

#### Parameters

**Path Parameters**

None

**Query Parameters**

None

**Request Body**

```json
{
  "token": "string", // The FCM registration token from the client device
  "deviceIdentifier": "string" // A unique identifier for the client device/browser instance
}
```

| Property           | Type   | Required | Description                                                 |
| ------------------ | ------ | -------- | ----------------------------------------------------------- |
| `token`            | string | Yes      | The Firebase Cloud Messaging registration token.            |
| `deviceIdentifier` | string | Yes      | A unique identifier for the client device/browser instance. |

#### Responses

**Success Response**

**Code**: 200 OK

Returns an object indicating the result of the operation.

```json
{
  "ok": true,
  "data": {
    "result": "unchanged | updated | created"
  }
}
```

| Property      | Type    | Description                                                                                                                       |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `ok`          | boolean | Indicates if the API call itself was successful.                                                                                  |
| `data`        | object  | Container for the response data.                                                                                                  |
| `data.result` | string  | Result status: 'unchanged' (token already exists for device), 'updated' (token updated), 'created' (new token/device registered). |

**Error Responses**

**Code**: 400 Bad Request

```json
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid or missing token/deviceIdentifier in request body"
    // ... potentially other validation fields
  }
}
```

**Code**: 401 Unauthorized

```json
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED | NO_ETHOS_PROFILE", // Service uses Forbidden, but route might map to Unauthorized
    "message": "Authentication required or no Ethos profile linked"
  }
}
```

#### Example

**Request**

```bash
# Needs auth token, a valid FCM token, and a device ID
FCM_TOKEN="bk3RNwTe3H0:CI2k_HHwgIpoDKCIZheNIo..."
DEVICE_ID="unique-browser-or-device-fingerprint"

http POST https://api.ethos.network/api/v1/notifications/user-fcm-token \
  Authorization:"Bearer <AUTH_TOKEN>" \
  token=$FCM_TOKEN \
  deviceIdentifier=$DEVICE_ID
```

**Response (Example: Token Created)**

```json
{
  "ok": true,
  "data": {
    "result": "created"
  }
}
```

#### Notes

* Requires authentication.
* Associates the provided FCM token with the authenticated user's profile and a specific device identifier.
* Allows the backend to send push notifications to the user's device via Firebase.
* Manages token updates and enforces a limit of 10 registered devices per profile.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.ethos.network/api-documentation/api-v1-deprecated/notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.