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

# Subscription API

> Integration of bot, billing and support: personal settings, themes, ads and Flow issuance rules.

The API manages the registration of existing Remnawave subscriptions. Changes are delivered when you update your subscription through Gateway Axottle. The API does not create tariffs, change traffic limits, or give access to other people's profiles.

The **Subscription Page → API** tab shows the paths for the selected connection.

## Authorization

You need a separate Bearer-token integration `axt_…`. Cookie-session panel, subscription link and the internal key page `axsp_…` for this API is not suitable.

An administrator with `settings.manage` creates a token through `POST /api/v1/internal-tokens` using administrative panel authorization.

```json theme={null}
{
  "name": "Биллинг: оформление подписок",
  "scopes": ["subscriptions:CONNECTION_ID:write"],
  "allowed_ips": []
}
```

Replace `CONNECTION_ID` with the ID of the desired connection. The secret is returned once in the `token` field, the token identifier in `token_info.id`. Keep the secret on the integration server, not in the client application.

| Area | Access | |
| - | - | - |
| `subscriptions:CONNECTION_ID:read` | Reading design, catalogs and preview | |
| `subscriptions:CONNECTION_ID:write` | Reading, changing and resetting settings, managing | connection ads |
| `subscription-flows:FLOW_ID:read` | Reading the Issue Rule for a Specific Flow and the History of | |
| `subscription-flows:FLOW_ID:write` | Reading and changing the issuance of a specific Flow | |

The general scope of `*` does not open this API. Connection rights do not give you the right to change Flow\.Flow right applies to all of its published profiles, including other connections.

`allowed_ips` limits the IP/CIDR of Axottle's direct network client. For reverse proxy, this is the proxy address, not the value of the client's `X-Forwarded-For`. The blank list does not limit the source over IP.

## Users and catalogues

Base path: `/api/subscriptions/v1/connections/CONNECTION_ID`.

| Method | Way relative to baseline | Result | |
| - | - | - | - |
| GET | `/users?q=NAME_OR_UUID` | Up to 50 users of the latest | sync |
| GET | `/users/USER_UUID` | Saved personal settings | |
| PATCH | `/users/USER_UUID` | Partial change; missed fields saved by | |
| PUT | `/users/USER_UUID` | Complete replacement; missed fields reset by | |
| DELETE | `/users/USER_UUID` | Reset personal settings, response 204 | |
| POST | `/users/USER_UUID/preview` | Preview without saving | |
| GET | `/themes` and `/themes/SLUG` | Theme Catalog and Color Profile | |
| GET | `/audiences` | Internal squads from Remnawave | |
| GET | `/flows` | Published Flow | Connections |

`USER_UUID` is the UUID of a Remnawave account, not a Telegram ID or subscription link token. The individual user's reading, recording and preview checks it in Remnawave. The response does not reveal the original link or configuration keys.

The main settings fields:

| Fields | Values | |
| - | - | - |
| `title` | Up to 25 characters; empty - the name of the original subscription | |
| `theme` | Slug from the directory, `resetcolors` or the empty string | |
| `announcement_mode` | `inherit` or `custom` | |
| `description`, `announcement` | Up to 200 characters each | |
| `announcement_until` | RFC3339 with time zone or `null` | |
| `support_notice`, `route_notice` | Boolean: support messages and changes to | connections |
| `support_url` | Public HTTPS link without login and password or empty line | |
| `routes_mode` | `inherit`, `prefer` or `only` | |
| `flow_ids` | Up to 32 unique Flow IDs and no more than 32 public profiles in total; for `prefer` and `only`, select a non-empty | |

Unknown fields are deflected. PATCH requires at least one field. PUT with an empty object resets all personal settings.

Example of a theme change and personal announcement; variables are set on the integration server:

```bash theme={null}
curl --request PATCH \
  "$AXOTTLE_URL/api/subscriptions/v1/connections/$CONNECTION_ID/users/$USER_UUID" \
  --header "Authorization: Bearer $SUBSCRIPTIONS_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"theme":"ocean","announcement_mode":"custom","announcement":"Вам ответили в поддержке"}'
```

The preview is taken by the **full draft** `settings`, not the partial PATCH:

```json theme={null}
{
  "settings": {
    "title": "Axottle",
    "theme": "ocean",
    "announcement_mode": "custom",
    "description": "Ваша подписка"
  },
  "user_agent": "Happ/3 iOS"
}
```

The result contains headings, topic applicability, selected message, audience matching, and Flow selection status.The actual intersection with available profiles is performed when a subscription is issued.

## Announcements

Use `GET /announcements`, `PUT /announcements/RULE_ID` and `DELETE /announcements/RULE_ID?version=N` regarding the connection path.

PUT accepts the complete rule. `version: 0`; to change, get the current version through GET. You must name up to 80 characters and text up to 200. `all`, `squad`, `user`; for the last two ask `targets` 1 to 32 identifiers. Exceptions are available. `excluded_users`priority 0-100, `starts_at` / `ends_at`platform `any` / `ios` / `android` / `desktop` precise `tag`.

The outdated version returns 400 at PUT, 409 at DELETE. Reread the rule and combine the changes; automatic rewrite can lose operator edits; up to 100 connection rules. [Priority of communications](https://docs.axottle.com/en/subscription-page/announcements.md#как-выбирается-сообщение) It matches the interface of the panel.

## Issue of Flow

| Method Method | Way |
| - | - |
| GET / PUT | `/api/subscriptions/v1/flows/FLOW_ID/subscription` |
| GET | `/api/subscriptions/v1/flows/FLOW_ID/subscription/history` |

GET returns `rule`related `nodes`, `profiles` and information about the old rules `legacy_rules`Change the required fields. `rule` and pass on **full rule** For a new record, the version is 0; the older version is rejected from 400. The exclusion state calculates the server.

Rule includes regime `drain_mode` (`off`, `manual`, `auto`), accessibility `health_enabled`load source `node_id`, thresholds, minimum duration of exclusion `hold_seconds`History returns up to 50 events in 30 days, requires a separate scope Flow and an affordable ConnectionUnits capability. [Assignment of settings](https://docs.axottle.com/en/subscription-page/presentation.md#общая-выдача-flow).

## Mistakes

| Code | Cause | |
| - | - | - |
| 400 | Incorrect fields, selection or version of the | rule |
| 401 | No token, unfaithful or withdrawn by | |
| 403 | Insufficient scope or IP restriction | |
| 404 | Requested resource not found | |
| 409 | Version conflict when deleting the | ad |
| 502 | Unable to Confirm Account in Remnawave | |

The error body has a `error` field. Receiving an error should not be considered a successful save.

## Verification

Start by reading the directory and settings of the test user. Perform a preview, then PATCH of one field and re-read. Update your subscription in the supported application. Separately check that the token does not have access to another connection or Flow.

## Rollback

Return the saved fields via PATCH or delete the personal settings via DELETE. For the ad rule or Flow, get the current version first and then save the previous values. Token recall via `DELETE /api/v1/internal-tokens/TOKEN_ID` prohibits subsequent requests, but does not cancel the changes already saved.

Examples use variables and conditional identifiers; requests to the workbar were not performed as part of the reconciliation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.