# X-Radius API - full reference

Base URL: https://x-radius.com/api/v1


## Users

### List subscribers

`GET /api/v1/users`

One page of subscribers under the caller's authority. A manager without tenant-wide visibility sees only subscribers owned by their own manager subtree, and that scope is injected server-side, so a filter can narrow within it but never widen past it.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read
- Rate limit bucket: `user_list`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | no | Searches username, email, first and last name, phone, contract id, national id and static IP. A purely numeric term also matches the subscriber id exactly. |
| `filter[enabled]` | query | boolean | no | The admin suspend flag. Not the same thing as expired. |
| `filter[expired]` | query | boolean | no | Subscription window has passed. |
| `filter[online]` | query | boolean | no | An open RADIUS session exists right now. |
| `filter[profile_id]` | query | integer | no | Bound plan. |
| `filter[parent_id]` | query | integer | no | Owning manager. Ignored, not honoured, when it would widen a restricted caller's scope. |
| `filter[username_exact]` | query | string | no | Case-insensitive exact username, for a caller that already knows the identity and wants one deterministic row instead of a page of substring hits. |
| `filter[expiring_within_days]` | query | integer | no | Future expiries only. |
| `filter[created_from]` | query | string | no | yyyy-MM-dd HH:mm:ss in UTC. A malformed value is a 400, not an ignored filter. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 4711,
      "tenant_id": 12,
      "username": "ahmed",
      "email": "ahmed@example.test",
      "enabled": true,
      "status": {
        "enabled": true,
        "deleted": false,
        "online": true,
        "expired": false,
        "have_quota": true,
        "fup": false,
        "can_connect": true
      },
      "profile_id": 7,
      "profile_name": "Home 20M",
      "parent_id": 41,
      "parent_username": "cairo-reseller",
      "bytes_remaining": 48318382080,
      "plan_bytes_limit": 107374182400,
      "used_bytes": 59055800320,
      "expiration": "2026-10-14 00:00:00",
      "balance": 0.00,
      "debt": 0.00,
      "mac_lock_enabled": false,
      "mac_locked_addrs": [],
      "enforces_bytes": true,
      "enforces_seconds": false,
      "created_at": "2026-03-02 11:40:12"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 812, "has_next": true }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | filter[created_from] is not a parseable timestamp |

#### Note

The per-subscriber scan token (lookup_token) is deliberately absent from list rows. It is served by GET /users/{id} and GET /users/resolve only, because a page of a thousand rows is a bulk harvest of codes that each unlock a subscriber record.


### Create a subscriber

`POST /api/v1/users`

Creates the account and its identity only. It does not activate a plan, take money or grant quota — binding profile_id here is metadata. Use the activation endpoint for the paid part.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_create` (Create users)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `username` | body | string | yes | Unique within the tenant, not globally. |
| `password` | body | string | yes | The RADIUS password. Stored recoverable, because CHAP and MS-CHAPv2 need it that way. |
| `parent_id` | body | integer | no | Owning manager. Defaults to the caller. A subscriber is never parent-less, and a named owner must be a manager the caller may act on. |
| `profile_id` | body | integer | no | Plan to bind. Must be one the acting manager may actually assign. |
| `expiration` | body | string | no | yyyy-MM-dd HH:mm:ss in UTC. |
| `debt_limit` | body | number | no | Credit ceiling. Omitted or null is unlimited, 0 is no credit. |
| `portal_password` | body | string | no | Optional portal-only password, hashed before storage and distinct from the RADIUS password above. |
| `custom_fields` | body | object | no | Tenant-defined form values, validated against the user form schema. |

#### Request

```json
{
  "username": "ahmed",
  "password": "s3cret-pass",
  "profile_id": 7,
  "parent_id": 41,
  "email": "ahmed@example.test",
  "phone": "+201000000000",
  "enabled": true,
  "debt_limit": 0
}
```

#### Response — 201 Created

```json
{
  "data": {
    "id": 4712,
    "tenant_id": 12,
    "username": "ahmed",
    "enabled": true,
    "profile_id": 7,
    "parent_id": 41,
    "balance": 0.00,
    "debt": 0.00,
    "created_at": "2026-09-20 09:14:55"
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | username or password missing, bad expiration, unassignable or inactive plan, unknown parent or group |
| `ERR_CONFLICT` | 409 | the username is taken in this tenant, or the licence subscriber cap is reached |
| `ERR_LICENSE_BLOCKED` | 403 | the tenant's licence has expired |

#### Note

debt_limit is tri-state and the two falsy values mean opposite things. Omitted or null is unlimited credit; 0 is no credit at all. Sending 0 to mean "no opinion" silently blocks every future debit.


### Extend subscription

`POST /api/v1/users/bulk-add-days`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_extend` (Extend subscription)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Extend subscription

`POST /api/v1/users/bulk-add-hours`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_extend` (Extend subscription)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add traffic

`POST /api/v1/users/bulk-add-traffic`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_add_traffic` (Add traffic)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete users

`POST /api/v1/users/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_delete` (Delete users)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Deposit to user wallet

`POST /api/v1/users/bulk-deposit`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_deposit` (Deposit to user wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Deposit to user wallet

`POST /api/v1/users/bulk-deposit/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_deposit` (Deposit to user wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Suspend many subscribers

`POST /api/v1/users/bulk-disable`

Takes an array of ids and suspends each. One request against the per-tenant write budget instead of one per subscriber, which is the difference between fitting in a minute and not.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_enable_disable` (Enable / suspend users)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ids` | body | array | yes | Subscriber ids. |

#### Request

```json
{
  "ids": [4711, 4712, 4713]
}
```

#### Response — 200 OK

```json
{
  "data": {
    "updated": [4711, 4713],
    "failed": [
      { "id": 4712, "reason": "not_authorized", "message": "You may not act on this record." }
    ]
  }
}
```

#### Note

A bulk call reports per-id outcomes and returns 200 even when some ids failed. failed is always present, as an array, and each entry carries a stable reason (not_found, not_authorized, error) alongside a localized message. Branch on reason; treating the 200 as "all of them worked" is the mistake this shape exists to prevent.


### Live traffic / disconnect

`POST /api/v1/users/bulk-disconnect`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_live_traffic` (Live traffic / disconnect)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Enable / suspend users

`POST /api/v1/users/bulk-enable`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_enable_disable` (Enable / suspend users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/users/bulk-extend

`POST /api/v1/users/bulk-extend`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_users_activate`, `prm_users_extend`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/users/bulk-extend/preview

`POST /api/v1/users/bulk-extend/preview`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_users_activate`, `prm_users_extend`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Withdraw / settle user debt

`POST /api/v1/users/bulk-reset-balance`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_withdrawal` (Withdraw / settle user debt)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reset user quota

`POST /api/v1/users/bulk-reset-quota`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_reset_quota` (Reset user quota)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Extend subscription

`POST /api/v1/users/bulk-set-expiration`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_extend` (Extend subscription)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Assign groups

`POST /api/v1/users/bulk-set-group`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_assign` (Assign groups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Change user parent

`POST /api/v1/users/bulk-set-parent`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_change_parent` (Change user parent)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Change user profile

`POST /api/v1/users/bulk-set-profile`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_change_profile` (Change user profile)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Withdraw / settle user debt

`POST /api/v1/users/bulk-withdraw`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_withdrawal` (Withdraw / settle user debt)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Withdraw / settle user debt

`POST /api/v1/users/bulk-withdraw/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_withdrawal` (Withdraw / settle user debt)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create users

`GET /api/v1/users/owner-context`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_create` (Create users)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Resolve a subscriber by scan code

`GET /api/v1/users/resolve`

Exchanges the opaque per-subscriber scan token, the one encoded in a printed QR code, for the subscriber record. Scoped to the caller's subtree exactly like a direct fetch.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read
- Rate limit bucket: `user_resolve`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | query | string | yes | The scan token. The QR payload is prefixed with xr:u: — strip the prefix before sending. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | code is missing or blank |
| `ERR_NOT_FOUND` | 404 | no subscriber carries that token, or they are outside the caller's subtree |


### Count subscribers by state

`GET /api/v1/users/summary`

Fleet-health counters over exactly the same authority scope as the list, so a count and the rows behind it always agree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

#### Response — 200 OK

```json
{
  "data": {
    "total": 812,
    "active": 640,
    "disabled": 44,
    "online": 318,
    "expired": 128
  }
}
```

#### Note

active means enabled AND not expired, not the bare enabled flag. total is every non-deleted subscriber, so the four other counters do not sum to it.


### Delete a subscriber

`DELETE /api/v1/users/{id}`

Soft-deletes the account and frees its username slot by renaming the row. The subscriber's live portal sessions are ended.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_delete` (Delete users)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 422 | the wallet balance is not zero — settle or withdraw it first |
| `ERR_NOT_FOUND` | 404 | no such subscriber, or one outside the caller's subtree |


### Fetch one subscriber

`GET /api/v1/users/{id}`

The full record, including the computed status object and the fields the list projection leaves out.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Response — 200 OK

```json
{
  "data": {
    "id": 4711,
    "tenant_id": 12,
    "username": "ahmed",
    "enabled": true,
    "status": { "online": true, "expired": false, "have_quota": true, "can_connect": true },
    "profile_id": 7,
    "fup_profile_id": null,
    "bytes_remaining": 48318382080,
    "seconds_remaining": null,
    "expiration": "2026-10-14 00:00:00",
    "balance": 0.00,
    "debt": 0.00,
    "debt_limit": null,
    "mac_lock_enabled": false,
    "mac_locked_addrs": [],
    "simultaneous_sessions": 1,
    "allowed_services": "both",
    "lookup_token": "n8Qk2vRa1pLd7WxYzB0cEf",
    "custom_fields": {},
    "created_at": "2026-03-02 11:40:12"
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such subscriber, or one outside the caller's manager subtree |

#### Note

A subscriber that exists but sits outside your subtree returns the same 404 as one that does not exist, byte for byte including details.reason. That is deliberate: a 403 would confirm the id and make the id space enumerable.


### Update a subscriber

`PATCH /api/v1/users/{id}`

Partial update. An omitted field is left alone. Three fields are separately permission-gated and are dropped silently rather than refused when the caller lacks the right: parent_id, profile_id and expiration.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `form_name` | body | string | no | Which custom-field schema to validate custom_fields against. Defaults to the user form. |

#### Request

```json
{
  "email": "new@example.test",
  "enabled": false,
  "mac_lock_enabled": true,
  "mac_locked_addrs": ["AA:BB:CC:DD:EE:FF"],
  "simultaneous_sessions": 2
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | bad expiration, unassignable or inactive plan, invalid allowed_services, a value Postgres itself refuses |
| `ERR_NOT_FOUND` | 404 | no such subscriber, or one outside the caller's subtree |

#### Note

A stored mac_locked_addrs list is inert until mac_lock_enabled is true. Writing the list alone locks nothing, which reads on screen like the lock silently failed. Set both.


### Un-suspend a subscriber

`POST /api/v1/users/{id}/activate`

Sets enabled back to true. This is the inverse of suspend and has nothing to do with activating a plan — that is the activation endpoint, which charges money.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_enable_disable` (Enable / suspend users)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such subscriber, or one outside the caller's subtree |

#### Note

The name is a historical trap. This endpoint lifts a suspension and takes no money. POST /users/{id}/activation is the one that prices, charges and provisions a plan.


### Charge and provision an activation

`POST /api/v1/users/{id}/activation`

Prices, charges and provisions in one operation. Funds are reserved first, then the plan is applied, and both halves are keyed off your request_id, so a retry after a crash re-runs neither the charge nor the grant.

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_users_activate`, `prm_users_extend`
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `request_id` | body | string | yes | Idempotency key, up to 255 characters, no colon or pipe. Reuse the same one on every retry of one intent. |
| `money_collected` | body | boolean | no | Defaults to true. |
| `card_code` | body | string | no | Required when method is card. The voucher must be in the caller's subtree. |
| `issue_invoice` | body | boolean | no | Also record an invoice document. Skipped on a replay so a retry never double-issues. |

#### Request

```json
{
  "profile_id": 7,
  "operation": "activate",
  "method": "manager_balance",
  "units": 1,
  "money_collected": true,
  "request_id": "0f3b9d4e-9a41-4c83-9b1e-2b6a0f1d88c2"
}
```

#### Response — 200 OK

```json
{
  "data": {
    "quote": { "profile_id": 7, "required_amount": 171.00, "new_expiration": "2026-10-14 00:00:00" },
    "activation": {
      "UserID": 4711,
      "ProfileID": 7,
      "NewSubscriptionEnd": "2026-10-14T00:00:00Z",
      "BytesRemaining": 107374182400,
      "SecondsRemaining": -1,
      "PointsAwarded": 10,
      "QuotaCarried": false,
      "Replay": false
    },
    "manager_balance": 4029.00,
    "replay": false
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | request_id missing, too long, or in a reserved namespace |
| `ERR_CONFLICT` | 409 | the request_id is already bound to an activation of a different subscriber |
| `ERR_FORBIDDEN` | 403 | the body's operation needs a permission the caller does not hold |

#### Note

The nested activation object is serialised with Go field names (UserID, NewSubscriptionEnd) and RFC3339 timestamps, unlike every other object on this API. Everything around it uses snake_case and yyyy-MM-dd HH:mm:ss. Do not write a parser that assumes one convention.


### Price an activation or extension

`POST /api/v1/users/{id}/activation-quote`

Read-only preview of what an activation would cost and grant: unit price, VAT, the computed new expiration, the plan's quota, both wallets, reward points and whether the chosen method can cover it. Writes nothing, so it is safe to call on every keystroke of a form.

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_users_activate`, `prm_users_extend`
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `profile_id` | body | integer | no | Plan to price. Defaults to the subscriber's current plan. |
| `operation` | body | enum | no | activate or extend. Defaults to activate. |
| `method` | body | enum | no | manager_balance, user_balance, reward_points or card. |
| `units` | body | integer | no | How many periods to buy. |
| `user_price` | body | number | no | Retail price override. Silently ignored for a caller without the price-override permission, which then falls back to the plan or pricing-tree price. |

#### Request

```json
{
  "profile_id": 7,
  "operation": "activate",
  "method": "manager_balance",
  "units": 1
}
```

#### Response — 200 OK

```json
{
  "data": {
    "user_id": 4711,
    "username": "ahmed",
    "profile_id": 7,
    "profile_name": "Home 20M",
    "operation": "activate",
    "method": "manager_balance",
    "units": 1,
    "unit_price": 150.00,
    "end_user_price": 180.00,
    "vat_percent": 14.00,
    "vat_amount": 21.00,
    "required_amount": 171.00,
    "price_overridden": false,
    "duration_value": 30,
    "duration_unit": "days",
    "total_bytes": 107374182400,
    "uptime_seconds": -1,
    "old_expiration": "2026-09-14 00:00:00",
    "new_expiration": "2026-10-14 00:00:00",
    "manager_balance": 4200.00,
    "manager_available": 4200.00,
    "user_balance": 0.00,
    "points_awarded": 10,
    "can_afford": true,
    "warnings": [],
    "debitable": false
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_FORBIDDEN` | 403 | the body's operation needs the extend permission and the caller only holds activate, or the reverse |

#### Note

A quota figure of -1 means unlimited, and 0 means none. They are not interchangeable and the difference is load-bearing on the RADIUS gate. Read uptime_seconds -1 above as "no time cap on this plan", not "no time left".


### Grant quota directly

`POST /api/v1/users/{id}/add-traffic`

Adds bytes and/or seconds to the subscriber's remaining period quota without pricing or charging anything, and drops the hot-path quota cache so the grant applies on the next RADIUS request.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_add_traffic` (Add traffic)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `bytes` | body | integer | no | Bytes to add. At least one of bytes or seconds must be present and positive. |
| `seconds` | body | integer | no | Seconds to add. |

#### Request

```json
{
  "bytes": 10737418240,
  "request_id": "7c2a0e91-6d44-4f9b-a1b7-0c5d3e8f2a10"
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | a negative value, or neither bytes nor seconds supplied |
| `ERR_NOT_FOUND` | 404 | no such subscriber |

#### Note

request_id is accepted here for your own tracing but is not enforced, because adding traffic is not naturally idempotent. Two calls add twice. Do not build a retry loop on this endpoint the way you would on deposit.


### Sell add-ons

`POST /api/v1/users/{id}/addon-quote`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_addon` (Sell add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell add-ons

`POST /api/v1/users/{id}/addons`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_addon` (Sell add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Approve pending signups

`POST /api/v1/users/{id}/approve`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_approve_signup` (Approve pending signups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit users

`POST /api/v1/users/{id}/assign-profile`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Set the bucket drain order

`PUT /api/v1/users/{id}/bucket-order`

Replaces the subscriber's custom drain order. Every id must be one of their active buckets, except the sentinel 0, which stands for the plan's own main quota and may be placed anywhere in the sequence.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_buckets` (Manage quota buckets)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `order` | body | array | yes | Bucket ids in drain order. 0 is the main quota, not a missing value. |

#### Request

```json
{
  "order": [331, 0, 402]
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an id is not one of this subscriber's active buckets, or the array is too long |

#### Note

The 0 in that array is meaningful and positional. It is the main plan quota, so stripping non-positive ids as "empty" would silently reorder the drain sequence rather than reject it.


### Cancel service

`POST /api/v1/users/{id}/cancel-service`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_cancel` (Cancel service)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Move a subscriber to another owner

`POST /api/v1/users/{id}/change-parent`

Re-points the subscriber at a different owning manager. The destination must be a manager the caller may act on, because the owner is both the creditor on a debt and the revenue attribution. Naturally idempotent, so request_id is accepted for your own tracing but is not enforced.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_change_parent` (Change user parent)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `parent_id` | body | integer | yes | The new owning manager. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | parent_id missing or not a manager in this tenant |
| `ERR_NOT_FOUND` | 404 | the subscriber or the destination manager is outside the caller's subtree |


### Change user profile

`POST /api/v1/users/{id}/change-profile`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_change_profile` (Change user profile)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Compensate users

`POST /api/v1/users/{id}/compensate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_compensate` (Compensate users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Approve/reject compensation requests

`POST /api/v1/users/{id}/compensations/{reqId}/approve`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_compensate_approve` (Approve/reject compensation requests)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Approve/reject compensation requests

`POST /api/v1/users/{id}/compensations/{reqId}/reject`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_compensate_approve` (Approve/reject compensation requests)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Remote access to user's CPE (router admin UI)

`POST /api/v1/users/{id}/cpe-console`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_remote` (Remote access to user's CPE (router admin UI))
- Risk: danger
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a subscriber's debt

`GET /api/v1/users/{id}/debt`

Total outstanding debt across all creditors, plus the slice of it owed to the calling manager specifically, read live off the loan ledger.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Response — 200 OK

```json
{
  "data": { "total": 340.00, "owed_to_me": 120.00 }
}
```


### Credit a subscriber wallet

`POST /api/v1/users/{id}/deposit`

Moves money into the subscriber's wallet and writes the matching ledger line. Idempotent on request_id through a unique constraint on the ledger itself, so the charge and the record of it cannot disagree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_deposit` (Deposit to user wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `amount` | body | number | yes | Major units, a bare JSON number. 150.50, not "150.50" and not 15050. |
| `request_id` | body | string | yes | Idempotency key. |
| `issue_invoice` | body | boolean | no | Also record an invoice document. Skipped on a replay. |

#### Request

```json
{
  "amount": 250.00,
  "request_id": "b41cf0a2-33de-4b57-8a7a-9e3c5d1f0c77"
}
```

#### Response — 200 OK

```json
{
  "data": {
    "journal_id": 90412,
    "balance": 250.00,
    "debt": 0.00,
    "replay": false
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | request_id missing, too long or reserved |
| `ERR_CONFLICT` | 409 | the request_id is already held by a different ledger line |

#### Note

replay true means this exact request already happened and nothing moved this time. It is a success, and the balance shown is the one from the original operation.


### Manage user documents

`GET /api/v1/users/{id}/documents`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user documents

`POST /api/v1/users/{id}/documents`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user documents

`POST /api/v1/users/{id}/documents/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user documents

`DELETE /api/v1/users/{id}/documents/{docId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user documents

`PATCH /api/v1/users/{id}/documents/{docId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user documents

`GET /api/v1/users/{id}/documents/{docId}/download`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_documents` (Manage user documents)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View free-zone traffic

`POST /api/v1/users/{id}/free-zone-traffic`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_freezone_traffic` (View free-zone traffic)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View free-zone traffic

`GET /api/v1/users/{id}/free-zones`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_freezone_traffic` (View free-zone traffic)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View usage history

`GET /api/v1/users/{id}/history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_history` (View usage history)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List one subscriber's invoices

`GET /api/v1/users/{id}/invoices`

Invoices belonging to a single subscriber, newest first.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_view` (View user invoices)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |


### Create an invoice for a subscriber

`POST /api/v1/users/{id}/invoices`

The per-subscriber form of issuing an invoice. Same validation and the same server-computed total; the subscriber comes from the path rather than the body.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_create` (Create user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `items` | body | array | yes | At least one line item. |


### Edit / pay user invoices

`POST /api/v1/users/{id}/invoices/bulk-pay`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_edit` (Edit / pay user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit / pay user invoices

`POST /api/v1/users/{id}/invoices/bulk-unpay`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_edit` (Edit / pay user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete an invoice

`DELETE /api/v1/users/{id}/invoices/{invoiceId}`

Deletes a hand-created invoice. Auto-issued documents cannot be deleted here, for the same reason they cannot be edited.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_delete` (Delete user invoices)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `invoiceId` | path | integer | yes | Invoice id. |


### Fetch one invoice

`GET /api/v1/users/{id}/invoices/{invoiceId}`

The invoice with its line items.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_view` (View user invoices)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `invoiceId` | path | integer | yes | Invoice id. |


### Edit an invoice

`PATCH /api/v1/users/{id}/invoices/{invoiceId}`

Edits a hand-created invoice. Auto-issued documents — activations, extensions, add-ons, deposits and withdrawals — are not editable through this path.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_edit` (Edit / pay user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `invoiceId` | path | integer | yes | Invoice id. |


### Mark an invoice paid

`POST /api/v1/users/{id}/invoices/{invoiceId}/pay`

Records the invoice as settled and stamps paid_on. This is bookkeeping: it does not move money between wallets.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_edit` (Edit / pay user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `invoiceId` | path | integer | yes | Invoice id. |

#### Note

Marking an invoice paid and taking a payment are different operations. This one changes a status; a deposit changes a balance. Doing one does not do the other.


### View user invoices

`GET /api/v1/users/{id}/invoices/{invoiceId}/render-data`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_view` (View user invoices)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Mark an invoice unpaid

`POST /api/v1/users/{id}/invoices/{invoiceId}/unpay`

Reverses the paid stamp. Again, bookkeeping only.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_invoices_edit` (Edit / pay user invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `invoiceId` | path | integer | yes | Invoice id. |


### View users

`GET /api/v1/users/{id}/journal`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Log in as subscriber

`POST /api/v1/users/{id}/login-as`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_login_as` (Log in as subscriber)
- Risk: danger
- Rate limit bucket: `user_login_as`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit users

`POST /api/v1/users/{id}/lookup-token/rotate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage parental controls

`GET /api/v1/users/{id}/parental`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_parental` (Manage parental controls)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage parental controls

`POST /api/v1/users/{id}/parental/reset-pin`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_parental` (Manage parental controls)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Withdraw / settle user debt

`POST /api/v1/users/{id}/pay-debt`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_withdrawal` (Withdraw / settle user debt)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View users

`GET /api/v1/users/{id}/payments`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List a subscriber's quota buckets

`GET /api/v1/users/{id}/quota-buckets`

Separately-metered grants layered on top of the plan's own quota — add-ons, extensions, card top-ups — in the order they will be drained.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 331,
      "source": "addon",
      "label": "Night 50GB",
      "priority": 10,
      "bytes_granted": 53687091200,
      "bytes_remaining": 41231686144,
      "seconds_granted": 0,
      "seconds_remaining": 0,
      "activated_at": "2026-09-12 20:04:01",
      "valid_until": "2026-10-12 20:04:01",
      "works_when_expired": false,
      "status": "active"
    }
  ],
  "meta": { "page": 1, "page_size": 1, "total": 1, "has_next": false }
}
```

#### Note

Un-paginated: the whole list is page 1 and has_next is always false. Do not write a paging loop against it. A subscriber may hold at most 50 active buckets, and a grant that would exceed the cap is refused before any money moves.


### Manage quota buckets

`POST /api/v1/users/{id}/quota-buckets/{bid}/cancel`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_buckets` (Manage quota buckets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View usage history

`GET /api/v1/users/{id}/quota-history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_history` (View usage history)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user RADIUS attributes

`GET /api/v1/users/{id}/radius-attrs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_radius_attributes` (Manage user RADIUS attributes)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user RADIUS attributes

`POST /api/v1/users/{id}/radius-attrs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_radius_attributes` (Manage user RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user RADIUS attributes

`POST /api/v1/users/{id}/radius-attrs/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_radius_attributes` (Manage user RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user RADIUS attributes

`DELETE /api/v1/users/{id}/radius-attrs/{attrId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_radius_attributes` (Manage user RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage user RADIUS attributes

`PATCH /api/v1/users/{id}/radius-attrs/{attrId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_radius_attributes` (Manage user RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View users

`GET /api/v1/users/{id}/receipts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Redeem reward points

`POST /api/v1/users/{id}/redeem-points`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_reward_points` (Redeem reward points)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Refund last activation

`POST /api/v1/users/{id}/refund-activation`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_refund` (Refund last activation)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Rename users

`POST /api/v1/users/{id}/rename`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_rename` (Rename users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit users

`POST /api/v1/users/{id}/reset-password`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reset quota counters

`POST /api/v1/users/{id}/reset-quota`

Always zeroes the daily counters. With clear_period true it also nulls the period quota, which is the destructive form. Lifts a daily FUP throttle and kicks the live session so full speed returns immediately. An empty body is accepted and means clear_period false.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_reset_quota` (Reset user quota)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `clear_period` | body | boolean | no | Also null the period quota counters. Defaults to false. |
| `reason` | body | string | no | Free-text note recorded on the quota-history audit row. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such subscriber |


### List a subscriber's session history

`GET /api/v1/users/{id}/sessions`

Accounting history for this subscriber, newest first, paginated with the standard list parameters.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_sessions_index` (View user sessions)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `filter[status]` | query | string | no | Narrows to open or closed sessions. |


### Edit users

`DELETE /api/v1/users/{id}/speed`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View users

`GET /api/v1/users/{id}/speed`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_index` (View users)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit users

`PUT /api/v1/users/{id}/speed`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_update` (Edit users)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Suspend a subscriber

`POST /api/v1/users/{id}/suspend`

Sets enabled to false and, when the tenant has disconnect-on-update enabled, kicks any live session so the suspension takes effect now rather than at the next re-auth.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_enable_disable` (Enable / suspend users)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |

#### Response — 200 OK

```json
{
  "data": {
    "id": 4711,
    "username": "ahmed",
    "enabled": false,
    "status": { "enabled": false, "can_connect": false }
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such subscriber, or one outside the caller's subtree |


### View usage history

`GET /api/v1/users/{id}/usage-history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_history` (View usage history)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debit a subscriber wallet

`POST /api/v1/users/{id}/withdraw`

The inverse of deposit. Refuses to take the balance below zero unless allow_negative is set.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_withdrawal` (Withdraw / settle user debt)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Subscriber id. |
| `amount` | body | number | yes | Major units. |
| `request_id` | body | string | yes | Idempotency key. |
| `allow_negative` | body | boolean | no | Permit the withdrawal to drive the balance below zero. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the request_id is already held by a different ledger line |



## Tickets

### View support tickets

`GET /api/v1/tickets`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/assignees`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/assignment-strategies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/blocklist`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/blocklist`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/blocklist/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/blocklist/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/bulk-assign`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/bulk-category`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/bulk-close`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/bulk-priority`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/bulk-reopen`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/bulk-resolve`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/bulk-snooze`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/bulk-team`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/canned-replies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/canned-replies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/canned-replies/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PUT /api/v1/tickets/canned-replies/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/categories`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/categories`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/categories/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PATCH /api/v1/tickets/categories/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/categories/{id}/fields`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/categories/{id}/fields`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/categories/{id}/fields/{fid}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PATCH /api/v1/tickets/categories/{id}/fields/{fid}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/counts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/form`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/macros`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/macros`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/macros/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PUT /api/v1/tickets/macros/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/sla/breaches`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/sla/calendars`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/sla/calendars`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/sla/calendars/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PUT /api/v1/tickets/sla/calendars/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/sla/policies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/sla/policies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/sla/policies/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PUT /api/v1/tickets/sla/policies/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/teams`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`POST /api/v1/tickets/teams`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`DELETE /api/v1/tickets/teams/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PATCH /api/v1/tickets/teams/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/teams/{id}/members`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`PUT /api/v1/tickets/teams/{id}/members`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/views`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`POST /api/v1/tickets/views`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`DELETE /api/v1/tickets/views/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`PATCH /api/v1/tickets/views/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/answers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/{id}/assign`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/attach`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`DELETE /api/v1/tickets/{id}/attachments/{attId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/attachments/{attId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/{id}/auto-assign`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage ticket categories & settings

`GET /api/v1/tickets/{id}/block-candidates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_config` (Manage ticket categories & settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`GET /api/v1/tickets/{id}/canned-replies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/{id}/claim`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/events`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add internal notes to support tickets

`POST /api/v1/tickets/{id}/internal-note`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_note` (Add internal notes to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/macros/{macroId}/apply`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/participants`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/participants`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`DELETE /api/v1/tickets/{id}/participants/{userId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/presence`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`POST /api/v1/tickets/{id}/presence`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`PUT /api/v1/tickets/{id}/priority`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`PUT /api/v1/tickets/{id}/read`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`GET /api/v1/tickets/{id}/reminders`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/reminders`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`DELETE /api/v1/tickets/{id}/reminders/{remId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/reopen`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/reply`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/resolve`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/tickets/{id}/sla`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/snooze`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Claim / assign support tickets

`POST /api/v1/tickets/{id}/team`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_assign` (Claim / assign support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reply to support tickets

`POST /api/v1/tickets/{id}/unsnooze`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_reply` (Reply to support tickets)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## NAS

### List NAS devices

`GET /api/v1/admin/nas`

Every NAS registered to the caller's tenant, with its reachability cache and the count of sessions currently on it.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 3,
      "tenant_id": 12,
      "nas_identifier": "cairo-edge-1",
      "nas_ip": "10.20.0.1",
      "description": "Nasr City edge",
      "vendor": "mikrotik",
      "model": "CCR2004",
      "coa_port": 3799,
      "ssh_port": 22,
      "winbox_port": 8291,
      "ip_accounting_enabled": true,
      "ping_status": "up",
      "last_ping_at": "2026-09-20 09:07:30",
      "last_rtt_ms": 4.2,
      "online_users": 118,
      "ping_fail_count": 0,
      "wg_enabled": true,
      "tunnel_transport": "wireguard",
      "active_tunnel_ip": "10.8.0.14",
      "zerologin_enabled": true,
      "needs_onboarding": false,
      "created_at": "2026-04-11 10:02:00"
    }
  ]
}
```

#### Note

Un-paginated, and there is no meta block at all. Do not write a paging loop against it. ping_status is a cached verdict from the background sweep, not a probe performed by your request — it is 'unknown' until the first sweep classifies the device.


### Register a NAS

`POST /api/v1/admin/nas`

Creates the device record and its RADIUS shared secret. At least one of nas_identifier, nas_ip and called_station_id must be present — that is what an incoming RADIUS packet will be matched on.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_create` (Add NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shared_secret` | body | string | yes | The RADIUS shared secret. Required. |
| `nas_identifier` | body | string | no | NAS-Identifier. Unique across the whole platform. |
| `nas_ip` | body | string | no | NAS-IP-Address. Unique across the whole platform. |
| `called_station_id` | body | string | no | Called-Station-Id. Unique across the whole platform. |
| `vendor` | body | string | no | Device vendor. Validated against the known-vendor catalogue. |
| `coa_port` | body | integer | no | RFC 5176 port. Omit for the schema default of 3799. |
| `ip_accounting_enabled` | body | boolean | no | Defaults to true when omitted. An explicit false is honoured. |

#### Request

```json
{
  "nas_identifier": "cairo-edge-2",
  "nas_ip": "10.20.0.2",
  "shared_secret": "a-long-random-secret",
  "description": "Nasr City edge 2",
  "vendor": "mikrotik",
  "coa_port": 3799
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | shared_secret missing, no identity field supplied, or an unknown vendor |
| `ERR_CONFLICT` | 409 | the nas_ip, nas_identifier or called_station_id is already registered — possibly by another tenant |

#### Note

A 409 here can be caused by a device belonging to a tenant you cannot see. The three identity columns are globally unique because RADIUS resolves on the bare key before any tenant is known, so "already taken" does not mean "already in your list".


### Edit NAS

`POST /api/v1/admin/nas/bulk-apply-hotspot`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/bulk-apply-parental`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete NAS

`POST /api/v1/admin/nas/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_delete` (Delete NAS)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/bulk-enable-zerologin`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List supported NAS vendors and models

`GET /api/v1/admin/nas/catalog`

The vendor and model catalogue the create and update endpoints validate against. Static data, safe to cache.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read


### View LAN devices

`GET /api/v1/admin/nas/device-groups`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_devices_index` (View LAN devices)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`POST /api/v1/admin/nas/device-groups`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`POST /api/v1/admin/nas/device-groups/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`DELETE /api/v1/admin/nas/device-groups/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`PATCH /api/v1/admin/nas/device-groups/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`GET /api/v1/admin/nas/device-groups/{id}/managers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage LAN device groups & manager access

`PUT /api/v1/admin/nas/device-groups/{id}/managers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_device_groups` (Manage LAN device groups & manager access)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View LAN devices

`GET /api/v1/admin/nas/devices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_devices_index` (View LAN devices)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/devices/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/devices/bulk-group`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`DELETE /api/v1/admin/nas/devices/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`PATCH /api/v1/admin/nas/devices/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Remote console to a LAN device

`POST /api/v1/admin/nas/devices/{id}/console`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_devices_remote` (Remote console to a LAN device)
- Risk: danger
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete NAS

`POST /api/v1/admin/nas/management-credentials/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_delete` (Delete NAS)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete NAS

`DELETE /api/v1/admin/nas/management-credentials/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_delete` (Delete NAS)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View NAS

`GET /api/v1/admin/nas/management-credentials/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/management-credentials/{id}/rotate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add NAS

`POST /api/v1/admin/nas/onboard`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_create` (Add NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Ping every NAS

`GET /api/v1/admin/nas/ping`

Probes all of the tenant's devices from the platform and reports reachability. An operator action.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read
- Rate limit bucket: `t_probe`

#### Note

On the per-tenant probe budget — 10 a minute on a standard licence, shared with every other probe endpoint. For continuous reachability, read ping_status off the NAS list instead: the background sweep maintains it for free.


### GET /api/v1/admin/nas/vpn/peers

`GET /api/v1/admin/nas/vpn/peers`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/nas/vpn/peers/bulk-delete

`POST /api/v1/admin/nas/vpn/peers/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### All VPN accounts (tenant-wide, incl. reassign)

`POST /api/v1/admin/nas/vpn/peers/bulk-reassign`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn_peers_all` (All VPN accounts (tenant-wide, incl. reassign))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/admin/nas/vpn/peers/{peerID}

`DELETE /api/v1/admin/nas/vpn/peers/{peerID}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/nas/vpn/peers/{peerID}/credentials

`GET /api/v1/admin/nas/vpn/peers/{peerID}/credentials`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/nas/vpn/peers/{peerID}/history

`GET /api/v1/admin/nas/vpn/peers/{peerID}/history`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### All VPN accounts (tenant-wide, incl. reassign)

`POST /api/v1/admin/nas/vpn/peers/{peerID}/reassign`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn_peers_all` (All VPN accounts (tenant-wide, incl. reassign))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/nas/vpn/peers/{peerID}/rotate

`POST /api/v1/admin/nas/vpn/peers/{peerID}/rotate`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/nas/vpn/servers

`GET /api/v1/admin/nas/vpn/servers`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a NAS

`DELETE /api/v1/admin/nas/{id}`

Removes the device record. Sessions already open on it are not affected.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_delete` (Delete NAS)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |


### Fetch one NAS

`GET /api/v1/admin/nas/{id}`

The full device record, including tunnel and operator-VPN configuration.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such NAS in this tenant |

#### Note

Read tunnel_transport to decide how to render a device, never "whichever tunnel IP is non-null". A NAS keeps its standby allocations after switching transport, so more than one of wg_tunnel_ip, ovpn_tunnel_ip and sstp_tunnel_ip is set on any device that ever changed. active_tunnel_ip is the database's own resolution of that question.


### Update a NAS

`PATCH /api/v1/admin/nas/{id}`

Partial update; an omitted field is left alone. The shared secret is not editable here — rotating it has its own endpoint, because it must be pushed to the device in step with the change.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | an identity field would clash with another device, anywhere on the platform |


### Edit NAS

`POST /api/v1/admin/nas/{id}/apply-hotspot`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/{id}/apply-parental`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Remote console (WebFig/SSH/Winbox) to a NAS router

`POST /api/v1/admin/nas/{id}/console`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_remote` (Remote console (WebFig/SSH/Winbox) to a NAS router)
- Risk: danger
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List devices behind a NAS

`GET /api/v1/admin/nas/{id}/devices`

Customer-premises and infrastructure devices discovered or registered under this NAS, as the monitoring and topology views see them.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_devices_index` (View LAN devices)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |


### Edit NAS

`POST /api/v1/admin/nas/{id}/devices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/{id}/enable-zerologin`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View NAS

`GET /api/v1/admin/nas/{id}/hotspot-preflight`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View NAS

`GET /api/v1/admin/nas/{id}/management-credentials`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add NAS

`POST /api/v1/admin/nas/{id}/management-credentials`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_create` (Add NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`GET /api/v1/admin/nas/{id}/management-script`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Render the onboarding script for a NAS

`GET /api/v1/admin/nas/{id}/onboarding-script`

Returns the RouterOS script that configures the device to talk to this platform: RADIUS client, accounting, the management tunnel and the captive portal redirect. Rendered for this specific device.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |

#### Note

The script contains the device's shared secret and tunnel credentials in the clear, because the router needs them. Treat the response as a secret, and do not log it.


### View NAS

`GET /api/v1/admin/nas/{id}/parental-script`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View NAS

`GET /api/v1/admin/nas/{id}/ping-history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_index` (View NAS)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/{id}/provision-tunnel`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/{id}/revert-hotspot`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Rotate a NAS shared secret

`POST /api/v1/admin/nas/{id}/rotate-secret`

Issues a new shared secret for the device. The router must be updated to match, or it stops authenticating — this endpoint changes the platform side only.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |

#### Note

There is no overlap window. From the moment this returns, RADIUS packets signed with the old secret are rejected. Push the new secret to the device in the same maintenance step.


### View LAN devices

`POST /api/v1/admin/nas/{id}/scan`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_devices_index` (View LAN devices)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reveal a NAS shared secret

`GET /api/v1/admin/nas/{id}/shared-secret`

Returns the device's RADIUS shared secret in the clear, for an operator re-entering it on the router. Gated on the NAS update permission rather than the read one, because seeing it is equivalent to being able to change it.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |


### Test a NAS connection

`POST /api/v1/admin/nas/{id}/test`

Checks that the platform can reach the device's management interface.

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_probe`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | NAS id. |


### Edit NAS

`POST /api/v1/admin/nas/{id}/test-ssh`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit NAS

`POST /api/v1/admin/nas/{id}/transport`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_update` (Edit NAS)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`GET /api/v1/admin/nas/{id}/vpn`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`PATCH /api/v1/admin/nas/{id}/vpn`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`POST /api/v1/admin/nas/{id}/vpn/disable`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`POST /api/v1/admin/nas/{id}/vpn/enable`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`GET /api/v1/admin/nas/{id}/vpn/history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/nas/{id}/vpn/peers

`POST /api/v1/admin/nas/{id}/vpn/peers`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_vpn_peers_own`, `prm_nas_vpn_peers_all`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### All VPN accounts (tenant-wide, incl. reassign)

`GET /api/v1/admin/nas/{id}/vpn/script`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn_peers_all` (All VPN accounts (tenant-wide, incl. reassign))
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Operator VPN access to NAS (issue/revoke VPN configs)

`POST /api/v1/admin/nas/{id}/vpn/zerotier/install-package`

- Authentication: manager session (JWT) or API token
- Permission: `prm_nas_vpn` (Operator VPN access to NAS (issue/revoke VPN configs))
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/nas/hotspot-asset

`GET /api/v1/nas/hotspot-asset`

- Authentication: none
- Rate limit bucket: `nas_provision`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/nas/provision

`GET /api/v1/nas/provision`

- Authentication: none
- Rate limit bucket: `nas_provision`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Portal

### PATCH /api/v1/portal/account

`PATCH /api/v1/portal/account`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/auto-renew

`POST /api/v1/portal/auto-renew`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/portal/bucket-order

`PUT /api/v1/portal/bucket-order`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/captcha

`GET /api/v1/portal/captcha`

- Authentication: none
- Rate limit bucket: `portal_captcha`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/cards/redeem

`POST /api/v1/portal/cards/redeem`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/change-profile

`POST /api/v1/portal/change-profile`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/config

`GET /api/v1/portal/config`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/credentials

`GET /api/v1/portal/credentials`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/deposit

`POST /api/v1/portal/deposit`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_deposit`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/exchange

`POST /api/v1/portal/exchange`

- Authentication: none
- Rate limit bucket: `portal_exchange`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/extend

`POST /api/v1/portal/extend`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/extensions

`GET /api/v1/portal/extensions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/extensions/{id}

`GET /api/v1/portal/extensions/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/guest/context

`GET /api/v1/portal/guest/context`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_guest`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/guest/register

`POST /api/v1/portal/guest/register`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_guest`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/invoices

`GET /api/v1/portal/invoices`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/invoices/{id}

`GET /api/v1/portal/invoices/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/invoices/{id}/render-data

`GET /api/v1/portal/invoices/{id}/render-data`

- Authentication: subscriber portal session
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/join

`POST /api/v1/portal/join`

- Authentication: none
- Rate limit bucket: `portal_join`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/join/context

`GET /api/v1/portal/join/context`

- Authentication: none
- Rate limit bucket: `portal_join`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/ledger

`GET /api/v1/portal/ledger`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/login

`POST /api/v1/portal/login`

- Authentication: none
- Rate limit bucket: `portal_login`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/me

`GET /api/v1/portal/me`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/parental

`GET /api/v1/portal/parental`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/parental/pause

`POST /api/v1/portal/parental/pause`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/parental/pin

`POST /api/v1/portal/parental/pin`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/portal/parental/rules

`PUT /api/v1/portal/parental/rules`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/parental/unlock

`POST /api/v1/portal/parental/unlock`

- Authentication: none
- Rate limit bucket: `portal_parental_unlock`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/password

`POST /api/v1/portal/password`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/payments/gateways

`GET /api/v1/portal/payments/gateways`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/payments/transactions

`GET /api/v1/portal/payments/transactions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/profiles

`GET /api/v1/portal/profiles`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/purchase

`POST /api/v1/portal/purchase`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_deposit`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/portal/push-tokens

`DELETE /api/v1/portal/push-tokens`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/push-tokens

`POST /api/v1/portal/push-tokens`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/quota-buckets

`GET /api/v1/portal/quota-buckets`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/quote

`POST /api/v1/portal/quote`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/refresh

`POST /api/v1/portal/refresh`

- Authentication: none
- Rate limit bucket: `portal_refresh`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/renew

`POST /api/v1/portal/renew`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/sessions

`GET /api/v1/portal/sessions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/signup

`POST /api/v1/portal/signup`

- Authentication: none
- Rate limit bucket: `portal_signup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/signup/schema

`GET /api/v1/portal/signup/schema`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/portal/speed

`DELETE /api/v1/portal/speed`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/speed

`GET /api/v1/portal/speed`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/portal/speed

`PUT /api/v1/portal/speed`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/telegram-exchange

`POST /api/v1/portal/telegram-exchange`

- Authentication: none
- Rate limit bucket: `portal_telegram_exchange`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/telegram/link

`GET /api/v1/portal/telegram/link`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/tickets

`GET /api/v1/portal/tickets`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/tickets

`POST /api/v1/portal/tickets`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/tickets/form

`GET /api/v1/portal/tickets/form`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/tickets/{id}

`GET /api/v1/portal/tickets/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/tickets/{id}/attach

`POST /api/v1/portal/tickets/{id}/attach`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/portal/tickets/{id}/attachments/{attId}

`DELETE /api/v1/portal/tickets/{id}/attachments/{attId}`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/tickets/{id}/attachments/{attId}

`GET /api/v1/portal/tickets/{id}/attachments/{attId}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/tickets/{id}/messages

`POST /api/v1/portal/tickets/{id}/messages`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/tunnel-identify

`POST /api/v1/portal/tunnel-identify`

- Authentication: none
- Rate limit bucket: `portal_tunnel_identify`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/portal/tunnel-tenant

`POST /api/v1/portal/tunnel-tenant`

- Authentication: none
- Rate limit bucket: `portal_tunnel_tenant`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/portal/usage

`GET /api/v1/portal/usage`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## User

### PATCH /api/v1/user/account

`PATCH /api/v1/user/account`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/auto-renew

`POST /api/v1/user/auto-renew`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/user/bucket-order

`PUT /api/v1/user/bucket-order`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/captcha

`GET /api/v1/user/captcha`

- Authentication: none
- Rate limit bucket: `portal_captcha`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/cards/redeem

`POST /api/v1/user/cards/redeem`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/change-profile

`POST /api/v1/user/change-profile`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/config

`GET /api/v1/user/config`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/credentials

`GET /api/v1/user/credentials`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/deposit

`POST /api/v1/user/deposit`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_deposit`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/exchange

`POST /api/v1/user/exchange`

- Authentication: none
- Rate limit bucket: `portal_exchange`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/extend

`POST /api/v1/user/extend`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/extensions

`GET /api/v1/user/extensions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/extensions/{id}

`GET /api/v1/user/extensions/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/guest/context

`GET /api/v1/user/guest/context`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_guest`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/guest/register

`POST /api/v1/user/guest/register`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_guest`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/invoices

`GET /api/v1/user/invoices`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/invoices/{id}

`GET /api/v1/user/invoices/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/invoices/{id}/render-data

`GET /api/v1/user/invoices/{id}/render-data`

- Authentication: subscriber portal session
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/join

`POST /api/v1/user/join`

- Authentication: none
- Rate limit bucket: `portal_join`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/join/context

`GET /api/v1/user/join/context`

- Authentication: none
- Rate limit bucket: `portal_join`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/ledger

`GET /api/v1/user/ledger`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/login

`POST /api/v1/user/login`

- Authentication: none
- Rate limit bucket: `portal_login`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/me

`GET /api/v1/user/me`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/parental

`GET /api/v1/user/parental`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/parental/pause

`POST /api/v1/user/parental/pause`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/parental/pin

`POST /api/v1/user/parental/pin`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/user/parental/rules

`PUT /api/v1/user/parental/rules`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/parental/unlock

`POST /api/v1/user/parental/unlock`

- Authentication: none
- Rate limit bucket: `portal_parental_unlock`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/password

`POST /api/v1/user/password`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/payments/gateways

`GET /api/v1/user/payments/gateways`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/payments/transactions

`GET /api/v1/user/payments/transactions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/profiles

`GET /api/v1/user/profiles`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/purchase

`POST /api/v1/user/purchase`

- Authentication: subscriber portal session
- Rate limit bucket: `portal_deposit`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/user/push-tokens

`DELETE /api/v1/user/push-tokens`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/push-tokens

`POST /api/v1/user/push-tokens`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/quota-buckets

`GET /api/v1/user/quota-buckets`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/quote

`POST /api/v1/user/quote`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/refresh

`POST /api/v1/user/refresh`

- Authentication: none
- Rate limit bucket: `portal_refresh`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/renew

`POST /api/v1/user/renew`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/sessions

`GET /api/v1/user/sessions`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/signup

`POST /api/v1/user/signup`

- Authentication: none
- Rate limit bucket: `portal_signup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/signup/schema

`GET /api/v1/user/signup/schema`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/user/speed

`DELETE /api/v1/user/speed`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/speed

`GET /api/v1/user/speed`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/user/speed

`PUT /api/v1/user/speed`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/telegram-exchange

`POST /api/v1/user/telegram-exchange`

- Authentication: none
- Rate limit bucket: `portal_telegram_exchange`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/telegram/link

`GET /api/v1/user/telegram/link`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/tickets

`GET /api/v1/user/tickets`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/tickets

`POST /api/v1/user/tickets`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/tickets/form

`GET /api/v1/user/tickets/form`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/tickets/{id}

`GET /api/v1/user/tickets/{id}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/tickets/{id}/attach

`POST /api/v1/user/tickets/{id}/attach`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/user/tickets/{id}/attachments/{attId}

`DELETE /api/v1/user/tickets/{id}/attachments/{attId}`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/tickets/{id}/attachments/{attId}

`GET /api/v1/user/tickets/{id}/attachments/{attId}`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/tickets/{id}/messages

`POST /api/v1/user/tickets/{id}/messages`

- Authentication: subscriber portal session
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/tunnel-identify

`POST /api/v1/user/tunnel-identify`

- Authentication: none
- Rate limit bucket: `portal_tunnel_identify`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/user/tunnel-tenant

`POST /api/v1/user/tunnel-tenant`

- Authentication: none
- Rate limit bucket: `portal_tunnel_tenant`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/user/usage

`GET /api/v1/user/usage`

- Authentication: subscriber portal session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Tools

### Manage announcements

`GET /api/v1/admin/tools/announcements`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_announcements` (Manage announcements)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage announcements

`POST /api/v1/admin/tools/announcements`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_announcements` (Manage announcements)
- Risk: write
- Rate limit bucket: `t_egress`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage announcements

`POST /api/v1/admin/tools/announcements/preview-count`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_announcements` (Manage announcements)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage announcements

`GET /api/v1/admin/tools/announcements/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_announcements` (Manage announcements)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`GET /api/v1/admin/tools/backup`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`POST /api/v1/admin/tools/backup`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`POST /api/v1/admin/tools/backup/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`GET /api/v1/admin/tools/backup/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`GET /api/v1/admin/tools/backup/jobs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`GET /api/v1/admin/tools/backup/schedule`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`PUT /api/v1/admin/tools/backup/schedule`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`POST /api/v1/admin/tools/backup/upload`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`DELETE /api/v1/admin/tools/backup/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`GET /api/v1/admin/tools/backup/{id}/download`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`POST /api/v1/admin/tools/backup/{id}/download-ticket`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Backup & restore

`POST /api/v1/admin/tools/backup/{id}/restore`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_backup` (Backup & restore)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`GET /api/v1/admin/tools/bandwidth`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`POST /api/v1/admin/tools/bandwidth/apply`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`GET /api/v1/admin/tools/bandwidth/history`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`GET /api/v1/admin/tools/bandwidth/schedules`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`POST /api/v1/admin/tools/bandwidth/schedules`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`POST /api/v1/admin/tools/bandwidth/schedules/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`DELETE /api/v1/admin/tools/bandwidth/schedules/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bandwidth control

`PATCH /api/v1/admin/tools/bandwidth/schedules/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bandwidth_control` (Bandwidth control)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bulk changes

`POST /api/v1/admin/tools/bulk/apply`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bulk_changes` (Bulk changes)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bulk changes

`GET /api/v1/admin/tools/bulk/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bulk_changes` (Bulk changes)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bulk changes

`GET /api/v1/admin/tools/bulk/jobs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bulk_changes` (Bulk changes)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bulk changes

`POST /api/v1/admin/tools/bulk/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_bulk_changes` (Bulk changes)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`GET /api/v1/admin/tools/dashboards`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`POST /api/v1/admin/tools/dashboards`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`POST /api/v1/admin/tools/dashboards/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`POST /api/v1/admin/tools/dashboards/restore-defaults`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`DELETE /api/v1/admin/tools/dashboards/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`GET /api/v1/admin/tools/dashboards/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`PUT /api/v1/admin/tools/dashboards/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Factory reset

`POST /api/v1/admin/tools/factory-reset`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_factory_reset` (Factory reset)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Factory reset

`GET /api/v1/admin/tools/factory-reset/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_factory_reset` (Factory reset)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### System maintenance

`GET /api/v1/admin/tools/maintenance/operations`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_maintenance` (System maintenance)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### System maintenance

`POST /api/v1/admin/tools/maintenance/run`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_maintenance` (System maintenance)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### System maintenance

`GET /api/v1/admin/tools/maintenance/runs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_maintenance` (System maintenance)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`GET /api/v1/admin/tools/widget-data/sources`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Dashboard Manager

`GET /api/v1/admin/tools/widget-data/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_dashboard_manager` (Dashboard Manager)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`GET /api/v1/admin/tools/widgets`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`POST /api/v1/admin/tools/widgets`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`POST /api/v1/admin/tools/widgets/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`DELETE /api/v1/admin/tools/widgets/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`GET /api/v1/admin/tools/widgets/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Widget Factory

`PUT /api/v1/admin/tools/widgets/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_widget_factory` (Widget Factory)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Monitoring

### View monitoring

`GET /api/v1/admin/monitoring/alerts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Acknowledge alerts

`POST /api/v1/admin/monitoring/alerts/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_ack` (Acknowledge alerts)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Acknowledge alerts

`POST /api/v1/admin/monitoring/alerts/clear-all`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_ack` (Acknowledge alerts)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/alerts/unacked-count`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Acknowledge alerts

`POST /api/v1/admin/monitoring/alerts/{id}/ack`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_ack` (Acknowledge alerts)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/alerts/{id}/deliveries`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`POST /api/v1/admin/monitoring/devices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`POST /api/v1/admin/monitoring/devices/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`DELETE /api/v1/admin/monitoring/devices/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`PUT /api/v1/admin/monitoring/devices/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`DELETE /api/v1/admin/monitoring/devices/{kind}/{ref}/geo`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`PUT /api/v1/admin/monitoring/devices/{kind}/{ref}/geo`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`PUT /api/v1/admin/monitoring/devices/{kind}/{ref}/icon`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/impact`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/live-traffic`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/live-traffic/stream`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/notify`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`PUT /api/v1/admin/monitoring/devices/{kind}/{ref}/notify`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/owners`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`PUT /api/v1/admin/monitoring/devices/{kind}/{ref}/owners`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`POST /api/v1/admin/monitoring/devices/{kind}/{ref}/ping`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/ping/stream`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`POST /api/v1/admin/monitoring/devices/{kind}/{ref}/share`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read
- Rate limit bucket: `t_egress`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/snmp-interfaces`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/stability`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/devices/{kind}/{ref}/users`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`PUT /api/v1/admin/monitoring/devices/{kind}/{ref}/users`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/geo`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/geo/hygiene`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`POST /api/v1/admin/monitoring/geo/import`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/geo/incidents`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/geo/links`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`POST /api/v1/admin/monitoring/geo/links`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`POST /api/v1/admin/monitoring/geo/links/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`DELETE /api/v1/admin/monitoring/geo/links/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`POST /api/v1/admin/monitoring/geo/links/{id}/reverse`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View network map

`GET /api/v1/admin/monitoring/map`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_view` (View network map)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit network map

`PUT /api/v1/admin/monitoring/map`

- Authentication: manager session (JWT) or API token
- Permission: `prm_map_edit` (Edit network map)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`POST /api/v1/admin/monitoring/sensors`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`POST /api/v1/admin/monitoring/sensors/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`DELETE /api/v1/admin/monitoring/sensors/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage monitored devices & sensors

`PUT /api/v1/admin/monitoring/sensors/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_manage` (Manage monitored devices & sensors)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View monitoring

`GET /api/v1/admin/monitoring/sensors/{id}/samples`

- Authentication: manager session (JWT) or API token
- Permission: `prm_monitoring_view` (View monitoring)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Managers

### Assign groups

`POST /api/v1/admin/managers/bulk-group`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_assign` (Assign groups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Assign groups

`POST /api/v1/admin/managers/{id}/group`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_assign` (Assign groups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List managers

`GET /api/v1/managers`

One page of managers. A caller without tenant-wide visibility sees their own descendants only — never their parent, never a sibling branch.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[parent_id]` | query | integer | no | Direct children of one manager. Also accepted as a bare parent_id query parameter. Narrows within the caller's subtree, never past it. |
| `q` | query | string | no | Searches name, username and email. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 57,
      "tenant_id": 12,
      "email": "giza@acme.example",
      "username": "giza-reseller",
      "firstname": "Mona",
      "status": "active",
      "parent_manager_id": 41,
      "parent_username": "cairo-reseller",
      "balance": 1840.00,
      "debt_limit": 5000.00,
      "debt": 0.00,
      "discount_rate": 10.00,
      "points_balance": 240,
      "users_count": 312,
      "created_at": "2026-05-02 09:00:00"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 9, "has_next": false }
}
```

#### Note

debt, parent_username, users_count and the other joined fields are computed by the list projection only. Fetching one manager by id returns the same record without them, so a client that reads users_count off a detail response will always see zero.


### Create a manager

`POST /api/v1/managers`

Creates a staff or reseller account. A manager needs at least one login identity, so email or username must be present.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_create` (Create managers)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `email` | body | string | no | Login email. Unique within the tenant. Required unless username is given. |
| `username` | body | string | no | Login username. Required unless email is given. |
| `password` | body | string | yes | Hashed with Argon2id before storage, unlike a subscriber's. |
| `parent_manager_id` | body | integer | no | Defaults to the caller. Never null — a tenant keeps exactly one root manager, its owner. A named parent must be one the caller may act on. |

#### Request

```json
{
  "email": "giza@acme.example",
  "username": "giza-reseller",
  "password": "a-strong-password",
  "firstname": "Mona",
  "parent_manager_id": 41
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the email is already registered in this tenant |
| `ERR_CONFLICT` | 409 | the licensed manager ceiling is reached |


### List managers for a picker

`GET /api/v1/managers/all`

Id and name only, un-paginated, for populating a select control. Same subtree scope as the full list.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read


### Edit managers

`POST /api/v1/managers/bulk-activate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete managers

`POST /api/v1/managers/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_delete` (Delete managers)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit managers

`POST /api/v1/managers/bulk-suspend`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a manager

`DELETE /api/v1/managers/{id}`

Hard-deletes the manager. Refused while they are still referenced by subscribers, card stock or ledger records — move those first.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_delete` (Delete managers)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 422 | the manager is still in use, or you are trying to delete yourself |
| `ERR_NOT_FOUND` | 404 | no such manager, or one outside the caller's subtree |


### Fetch one manager

`GET /api/v1/managers/{id}`

The manager record, including their custom form fields.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such manager, or one outside the caller's subtree |


### Update a manager

`PATCH /api/v1/managers/{id}`

Partial update. An omitted field is left alone.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such manager, or one outside the caller's subtree |


### Edit managers

`POST /api/v1/managers/{id}/2fa/reset`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit managers

`POST /api/v1/managers/{id}/activate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a manager's debt

`GET /api/v1/managers/{id}/debt`

Outstanding debt for this manager, read off the loan ledger.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_journal` (View manager journal)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |


### View manager invoices

`GET /api/v1/managers/{id}/invoices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_invoices` (View manager invoices)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a manager's ledger

`GET /api/v1/managers/{id}/journal`

Every money movement on this manager's wallet, newest first, with a running balance. This is the authoritative record — the wallet balance is its consequence, not a parallel truth.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_journal` (View manager journal)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |


### View manager journal

`GET /api/v1/managers/{id}/loans`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_journal` (View manager journal)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Log in as manager

`POST /api/v1/managers/{id}/login-as`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_login_as` (Log in as manager)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View managers

`GET /api/v1/managers/{id}/overview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View manager receipts

`GET /api/v1/managers/{id}/payments`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_receipts` (View manager receipts)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add / deduct manager reward points

`POST /api/v1/managers/{id}/points/add`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_reward_points` (Add / deduct manager reward points)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Add / deduct manager reward points

`POST /api/v1/managers/{id}/points/deduct`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_reward_points` (Add / deduct manager reward points)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View managers

`GET /api/v1/managers/{id}/profile`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View manager receipts

`GET /api/v1/managers/{id}/receipts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_receipts` (View manager receipts)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit managers

`POST /api/v1/managers/{id}/reset-password`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a manager's roles

`GET /api/v1/managers/{id}/roles`

The roles assigned to this manager, which is what their permissions resolve from.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_index` (View managers)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |


### Replace a manager's roles

`PUT /api/v1/managers/{id}/roles`

Replaces the whole set. A caller may only grant roles whose permissions are a subset of their own, so this cannot be used to escalate.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |
| `role_ids` | body | array | yes | The complete new set of role ids. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_FORBIDDEN` | 403 | the caller holds an API token — this route refuses machine credentials |

#### Note

This takes effect on every API token that manager holds, immediately and silently. A token's authority is its owner's live permissions intersected with its own scope, so removing a role here shrinks every integration running as that person with no notification and no change to the token record.


### Suspend a manager

`POST /api/v1/managers/{id}/suspend`

Sets the account to suspended. They can no longer sign in, and every API token they own stops authenticating with reason api_token_owner_inactive.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_update` (Edit managers)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |

#### Note

Suspending a reseller does not touch the subscribers below them. Those keep connecting; only the person's own access ends.


### Credit a manager wallet

`POST /api/v1/managers/{id}/wallet/deposit`

Moves money into a reseller's wallet and posts the matching ledger entry. Idempotent on request_id through the ledger's own unique constraint.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_deposit` (Deposit to manager wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. May not be the caller themselves. |
| `amount` | body | number | yes | Major units, a bare JSON number. |
| `request_id` | body | string | yes | Idempotency key. |
| `reason` | body | string | no | Free-text note recorded on the ledger row. |
| `issue_invoice` | body | boolean | no | Also record the human-facing accounting document. Defaults to TRUE when omitted on the manager side, unlike the subscriber side. |

#### Request

```json
{
  "amount": 5000.00,
  "reason": "bank transfer 2026-09-20",
  "request_id": "e1a7b204-1c4f-4a2e-8d66-90b3f7c1d452"
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the request_id is already held by a different ledger line |

#### Note

issue_invoice defaults differently here than on the subscriber wallet. Omitting it on a manager deposit issues the document; omitting it on a subscriber deposit does not. Send it explicitly if you care either way.


### Settle a manager's debt

`POST /api/v1/managers/{id}/wallet/pay-debt`

Records a repayment against a creditor. The creditor defaults to the debtor's parent manager.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_pay_debt` (Settle manager debt)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | The debtor. May not be the caller themselves. |
| `amount` | body | number | yes | Major units. |
| `creditor_manager_id` | body | integer | no | Which creditor is being repaid. Absent means the debtor's parent. |
| `request_id` | body | string | yes | Idempotency key. |


### Deposit to manager wallet

`POST /api/v1/managers/{id}/wallet/topup`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_deposit` (Deposit to manager wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debit a manager wallet

`POST /api/v1/managers/{id}/wallet/withdraw`

The inverse of deposit, posting the matching ledger entry.

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_withdrawal` (Withdraw from manager wallet)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Manager id. |
| `amount` | body | number | yes | Major units. |
| `request_id` | body | string | yes | Idempotency key. |
| `allow_negative` | body | boolean | no | Permit the withdrawal to drive the balance below zero. |



## Public

### POST /api/v1/public/auth/resolve-host

`POST /api/v1/public/auth/resolve-host`

- Authentication: none
- Rate limit bucket: `resolve_host`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/backup/oauth/{provider}/callback

`GET /api/v1/public/backup/oauth/{provider}/callback`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/csat/{token}

`GET /api/v1/public/csat/{token}`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/csat/{token}

`POST /api/v1/public/csat/{token}`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/csp-report

`POST /api/v1/public/csp-report`

- Authentication: none
- Rate limit bucket: `csp_report`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/pay/gateways

`GET /api/v1/public/pay/gateways`

- Authentication: none
- Rate limit bucket: `pay_guest_gateways`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/pay/guest-checkout

`POST /api/v1/public/pay/guest-checkout`

- Authentication: none
- Rate limit bucket: `pay_guest_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/pay/lookup

`POST /api/v1/public/pay/lookup`

- Authentication: none
- Rate limit bucket: `pay_guest_lookup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/pay/recover

`POST /api/v1/public/pay/recover`

- Authentication: none
- Rate limit bucket: `pay_guest_recover`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/pay/status/{state}

`GET /api/v1/public/pay/status/{state}`

- Authentication: none
- Rate limit bucket: `pay_status`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/pay/{gateway}/redirect/{tenant_id}/{token}/{outcome}

`GET /api/v1/public/pay/{gateway}/redirect/{tenant_id}/{token}/{outcome}`

- Authentication: none
- Rate limit bucket: `pay_return`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/pay/{gateway}/return/{state}

`GET /api/v1/public/pay/{gateway}/return/{state}`

- Authentication: none
- Rate limit bucket: `pay_return`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/pay/{gateway}/webhook/{tenant_id}/{secret}

`POST /api/v1/public/pay/{gateway}/webhook/{tenant_id}/{secret}`

- Authentication: none
- Rate limit bucket: `pay_webhook`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/register/captcha

`GET /api/v1/public/register/captcha`

- Authentication: none
- Rate limit bucket: `register_captcha`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/register/policy

`GET /api/v1/public/register/policy`

- Authentication: none
- Rate limit bucket: `register_policy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/register/slug-available

`GET /api/v1/public/register/slug-available`

- Authentication: none
- Rate limit bucket: `slug_available`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/site/captcha

`GET /api/v1/public/site/captcha`

- Authentication: none
- Rate limit bucket: `site_captcha`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/site/leads

`POST /api/v1/public/site/leads`

- Authentication: none
- Rate limit bucket: `site_leads`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### CONNECT /api/v1/public/sysbackup/{name}

`CONNECT /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/public/sysbackup/{name}

`DELETE /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/public/sysbackup/{name}

`GET /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### HEAD /api/v1/public/sysbackup/{name}

`HEAD /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### OPTIONS /api/v1/public/sysbackup/{name}

`OPTIONS /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PATCH /api/v1/public/sysbackup/{name}

`PATCH /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/sysbackup/{name}

`POST /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/public/sysbackup/{name}

`PUT /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### QUERY /api/v1/public/sysbackup/{name}

`QUERY /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### TRACE /api/v1/public/sysbackup/{name}

`TRACE /api/v1/public/sysbackup/{name}`

- Authentication: none
- Rate limit bucket: `sysbackup`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/public/telegram/{bot_kind}/webhook/{license_id}/{secret}

`POST /api/v1/public/telegram/{bot_kind}/webhook/{license_id}/{secret}`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Card Batches

### List card series

`GET /api/v1/card-batches`

One page of card series with their stock breakdown. A non-admin caller sees only series created within their own manager subtree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[status]` | query | string | no | Generation status — generating, ready, failed. |
| `filter[card_mode]` | query | string | no | The series mode. |
| `filter[owner_manager_id]` | query | integer | no | The reseller holding the series after any transfer. |
| `filter[suspended]` | query | boolean | no | Series whose unused cards have been revoked. |
| `filter[template_id]` | query | integer | no | Series cut from one saved card template. |
| `q` | query | string | no | Plan name, distribution note, or series id. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 208,
      "plan_id": 7,
      "plan_name": "Home 20M",
      "card_mode": "voucher_account",
      "quantity": 500,
      "face_value": 150.00,
      "code_length": 10,
      "code_charset": "alnum_no_ambig",
      "status": "ready",
      "suspended": false,
      "processed": 500,
      "used": 312,
      "available": 171,
      "sold_online": 9,
      "sold_counter": 8,
      "stuck_sale": 0,
      "expiration": "2027-01-01 00:00:00",
      "printed_at": "2026-08-30 12:01:44",
      "print_count": 1,
      "pdf_ready": true,
      "has_cards": true,
      "owner_manager_id": 41,
      "sell_online": false,
      "auto_activate": false,
      "created_by": 41
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 24, "has_next": false }
}
```

#### Note

Never derive stock by subtraction. used excludes both unused and revoked, so quantity minus used is not the unused count, and quantity itself grows when the point of sale mints into the series. available is the sellable stock. stuck_sale is a warning, not a bucket: it counts cards held by a till sale that never completed, and there is no reaper for it.


### Generate a card series

`POST /api/v1/card-batches`

Stages an asynchronous generation job and returns immediately. The cards and the printable artifact are produced in the background; poll the series until status is ready, then fetch the print job.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_generate_user` (Generate user cards)
- Risk: write
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | body | enum | yes | refill or prepaid. |
| `quantity` | body | integer | yes | How many cards to mint. |
| `face_value` | body | number | yes | Value per card, major units. |
| `expiration` | body | string | yes | yyyy-MM-dd HH:mm:ss or yyyy-MM-dd. Series-level card lifetime. |
| `plan_profile_id` | body | integer | no | Required for prepaid, and for a refill card that auto-activates. |
| `code_length` | body | integer | no | The redemption PIN length. A MINIMUM, not an exact value — a mint may exceed it when the tenant's live code pool needs more entropy. |
| `code_charset` | body | enum | no | numeric, alpha, alnum or alnum_no_ambig. |
| `owner_manager_id` | body | integer | no | The series owner. Defaults to the creator. |
| `request_id` | body | string | yes | Idempotency key. |

#### Request

```json
{
  "type": "prepaid",
  "quantity": 500,
  "face_value": 150.00,
  "expiration": "2027-01-01",
  "plan_profile_id": 7,
  "code_length": 10,
  "code_charset": "alnum_no_ambig",
  "request_id": "5f2a7c18-2b0d-4a61-9f3e-7a4c8d2e1b09"
}
```

#### Response — 202 Accepted

```json
{
  "data": {
    "batch_id": 209,
    "mode": "voucher_account",
    "status": "generating",
    "replay": false
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | bad expiration, an unworkable spec, or a request_id that is missing, too long or reserved |
| `ERR_VALIDATION` | 402 | the generating manager's wallet cannot cover the generation charge |
| `ERR_FORBIDDEN` | 403 | minting refill cards without the refill-generation permission, which is separate from the generate permission the route checks |

#### Note

A fresh stage answers 202 Accepted; a replay of the same request_id answers 200 OK with the original batch_id and replay true. The status field says generating in both cases, because it describes the job, not the outcome of this call. Branch on the HTTP status or on replay, not on status.


### Delete card batches

`POST /api/v1/card-batches/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_delete` (Delete card batches)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Change card expiry

`POST /api/v1/card-batches/bulk-expiry`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_change_expiry` (Change card expiry)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Download / export cards

`POST /api/v1/card-batches/bulk-print-job`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_download` (Download / export cards)
- Risk: write
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Download / export cards

`POST /api/v1/card-batches/bulk-printed`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_download` (Download / export cards)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Suspend / release cards

`POST /api/v1/card-batches/bulk-release`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_suspend_release` (Suspend / release cards)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Suspend / release cards

`POST /api/v1/card-batches/bulk-suspend`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_suspend_release` (Suspend / release cards)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Generate user cards

`GET /api/v1/card-batches/code-length`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_generate_user` (Generate user cards)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a card series

`DELETE /api/v1/card-batches/{id}`

Deletes the series and its cards. Refuses outright once any card in it has been redeemed, transferred or sold at the till, because those are financial records.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_delete` (Delete card batches)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the series has redemptions, transfers, or counter sales |


### Fetch one card series

`GET /api/v1/card-batches/{id}`

The series header, its generation spec and its stock breakdown.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such series, or one outside the caller's subtree |


### Manage card designs

`PATCH /api/v1/card-batches/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_designer` (Manage card designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List the cards in a series

`GET /api/v1/card-batches/{id}/cards`

One row per card, carrying the plaintext code and, for prepaid series, the login username and password. Behind both the card-list permission and the per-series subtree gate for that reason.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |
| `filter[state]` | query | string | no | Stored state — unused, consumed, active, exhausted, revoked. |
| `filter[disposition]` | query | string | no | Who holds the card, which is orthogonal to state. |
| `filter[has_customer]` | query | boolean | no | Cards linked to a subscriber. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 90211,
      "serial": "000312",
      "code": "K7P4M2Q9XD",
      "username": "v90211",
      "password": "8sk3ndq1",
      "state": "unused",
      "effective_state": "unused",
      "disposition": "available",
      "redemptions_left": 1,
      "expires_at": "2027-01-01 00:00:00",
      "used_bytes": 0,
      "used_seconds": 0
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 500, "has_next": true }
}
```

#### Note

state and effective_state are different questions and you almost always want the second. Nothing ever writes state 'expired', so a voucher past its expiry still reads as 'unused' in state and shows as available stock; effective_state applies the expiry at read time. Meanwhile disposition answers who holds the card — a voucher sold at the till but not yet redeemed is still 'unused' and is not stock you can sell again.


### Change card expiry

`POST /api/v1/card-batches/{id}/expiry`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_change_expiry` (Change card expiry)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Download / export cards

`GET /api/v1/card-batches/{id}/pdf`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_download` (Download / export cards)
- Risk: write
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View card batches & cards

`GET /api/v1/card-batches/{id}/pricing`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage card designs

`DELETE /api/v1/card-batches/{id}/pricing/{resellerId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_designer` (Manage card designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage card designs

`PUT /api/v1/card-batches/{id}/pricing/{resellerId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_designer` (Manage card designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Fetch a series' print job

`GET /api/v1/card-batches/{id}/print-job`

The data a client needs to render the printable sheet in the browser. Rendering happens client-side; the server ships no PDF engine.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_download` (Download / export cards)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |


### Mark a series printed

`POST /api/v1/card-batches/{id}/printed`

Records that the sheet was rendered, stamping printed_at and incrementing print_count.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_download` (Download / export cards)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |

#### Note

Print tracking is observational only and deliberately does NOT move the series status. Nothing may set status to 'printed': the till refuses to mint into any series whose status is not 'ready', so auto-stamping would silently close every printed series to counter top-ups.


### Generate user cards

`POST /api/v1/card-batches/{id}/regenerate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_generate_user` (Generate user cards)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Release a suspended card series

`POST /api/v1/card-batches/{id}/release`

Puts the revoked-but-unused cards of a suspended series back into stock.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_suspend_release` (Suspend / release cards)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |


### Suspend a card series

`POST /api/v1/card-batches/{id}/suspend`

Revokes every still-unused card in the series. Cards already in flight are left alive. Re-running it is a harmless no-op.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_suspend_release` (Suspend / release cards)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |

#### Response — 200 OK

```json
{
  "data": { "message_key": "card_batch_suspended" }
}
```


### Transfer N cards from a series

`POST /api/v1/card-batches/{id}/transfer-count`

Like transfer-whole, but moves a count of cards off the top of the available stock rather than the entire series.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_change_owner` (Transfer / change card owner)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |
| `count` | body | integer | yes | How many cards to move. |
| `from_manager_id` | body | integer | yes | The current holder. |
| `to_manager_id` | body | integer | yes | The receiving reseller. |
| `unit_price` | body | number | yes | Price per card. Required, never defaulted to zero. |
| `request_id` | body | string | yes | Idempotency key. |


### Transfer a card id range

`POST /api/v1/card-batches/{id}/transfer-range`

Moves a contiguous range of card ids from the series, for the case where the physical cards handed over are a known block.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_change_owner` (Transfer / change card owner)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |
| `card_id_range` | body | object | yes | The inclusive id range to move. |
| `unit_price` | body | number | yes | Price per card. Required. |
| `request_id` | body | string | yes | Idempotency key. |


### Transfer a whole series to another reseller

`POST /api/v1/card-batches/{id}/transfer-whole`

Moves every card in the series from one manager to another at an agreed unit price, posting the matching ledger entries on both sides.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_change_owner` (Transfer / change card owner)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Series id. |
| `from_manager_id` | body | integer | yes | The current holder. |
| `to_manager_id` | body | integer | yes | The receiving reseller. |
| `unit_price` | body | number | yes | Price per card, major units. Must be sent explicitly — omitting it is an error, not a zero. |
| `request_id` | body | string | yes | Idempotency key. |

#### Request

```json
{
  "from_manager_id": 41,
  "to_manager_id": 57,
  "unit_price": 140.00,
  "request_id": "c8e1a4b9-7f30-4d62-b0a5-6e2c9d3f1074"
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | unit_price omitted, or a request_id that is missing, too long or reserved |
| `ERR_CONFLICT` | 409 | the request_id is already bound to a different transfer |

#### Note

unit_price is a required tri-state and omitting it is refused rather than read as zero. A bare 0 from a client that simply left the field out would mean "give the stock away", which is exactly the defect this check exists to stop. A negative price inverts the transfer.


### View card batches & cards

`GET /api/v1/card-batches/{id}/transferable-cards`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View card batches & cards

`GET /api/v1/card-batches/{id}/transfers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Profiles

### List plans

`GET /api/v1/profiles`

One page of service plans, scoped to what the calling manager may actually see. A private plan is visible only to managers it was explicitly allow-listed for.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_index` (View profiles)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[type]` | query | enum | no | prepaid, postpaid, fup, extension or addon. |
| `filter[status]` | query | string | no | Plan status. |
| `filter[assignable]` | query | boolean | no | Only plans this caller may bind to a subscriber. Narrower than visibility, and the right filter behind a plan picker. |
| `filter[allowed_services]` | query | enum | no | ppp, hotspot or both. |
| `filter[show_in_ucp]` | query | boolean | no | Plans the subscriber portal offers for self-service renewal. |
| `filter[private]` | query | boolean | no | Plans restricted to an explicit manager allow-list. |
| `filter[has_fup_chain]` | query | boolean | no | Plans that fall back to another plan on expiry or quota exhaustion. |
| `sort` | query | string | no | id, created_at, name, type or status. Defaults to name ascending. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 7,
      "tenant_id": 12,
      "name": "Home 20M",
      "type": "prepaid",
      "base_fee": 150.00,
      "end_user_price": 180.00,
      "vat_percent": "14.00",
      "enforce_expiration": true,
      "expiration_value": 30,
      "expiration_unit": "days",
      "combined_bytes_limit": 107374182400,
      "enforce_combined_bytes": true,
      "enforce_period_seconds": false,
      "download_kbps": 20480,
      "upload_kbps": 4096,
      "speed_share_mode": "per_session",
      "allowed_services": "both",
      "private": false,
      "show_in_ucp": true,
      "carry_over_remaining_quota": false,
      "auto_renew_supported": true,
      "points_award": 10
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 18, "has_next": false }
}
```

#### Note

vat_percent is a STRING, not a number. It is a NUMERIC(5,2) in the database and is serialised as text so the exact value survives the round trip. Every other money field on the plan is a bare JSON number.


### Create a plan

`POST /api/v1/profiles`

name and type are the only required fields; everything else has a schema default. A plan created with no enforce toggles on is an unlimited plan.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_create` (Create profiles)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | body | string | yes | Display name. |
| `type` | body | enum | yes | prepaid, postpaid, fup, extension or addon. |
| `base_fee` | body | number | no | Wholesale price to the reseller, major units. |
| `end_user_price` | body | number | no | Retail price, major units. |
| `expiration_value` | body | integer | no | Period length, paired with expiration_unit. |
| `expiration_unit` | body | enum | no | hours, days or months. |

#### Request

```json
{
  "name": "Home 20M",
  "type": "prepaid",
  "base_fee": 150.00,
  "end_user_price": 180.00,
  "enforce_expiration": true,
  "expiration_value": 30,
  "expiration_unit": "days",
  "enforce_combined_bytes": true,
  "combined_bytes_limit": 107374182400,
  "download_kbps": 20480,
  "upload_kbps": 4096
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | name or type missing, or an out-of-range value |

#### Note

A quota limit does nothing until its enforce toggle is on. Setting combined_bytes_limit while enforce_combined_bytes is false leaves the plan unlimited on data, and the number sits there looking like a cap. The two always travel together.


### List plans for a picker

`GET /api/v1/profiles/all`

Id and name only, un-paginated, for populating a select control. Cheaper than the full list when you do not need the plan bodies.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_index` (View profiles)
- Risk: read


### Delete profiles

`POST /api/v1/profiles/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_delete` (Delete profiles)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a plan

`DELETE /api/v1/profiles/{id}`

Refused while the plan is still referenced — by a subscriber, a card series or another plan's fall-back chain.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_delete` (Delete profiles)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the plan is still in use |


### Fetch one plan

`GET /api/v1/profiles/{id}`

The full plan definition: pricing, quota limits and their enforce toggles, speed, lifecycle flags and the fall-back chain.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_index` (View profiles)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such plan, or one this manager may not see |

#### Note

A plan you may not see answers 404, identical to one that does not exist. This route carries wholesale terms (base_fee, max_price), so a 403 would have let a reseller walk plan ids and read a rival's private pricing.


### Update a plan

`PATCH /api/v1/profiles/{id}`

Partial update. Numeric and foreign-key fields can be cleared to null by sending null explicitly, which is distinct from omitting them.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_update` (Edit profiles)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |

#### Note

Editing a plan does not re-provision the subscribers already on it. Their quota and window were written at activation time; a price or limit change applies to the next activation, not retroactively.


### Manage profile visibility / policy

`GET /api/v1/profiles/{id}/allowed-extensions`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage profile visibility / policy

`PUT /api/v1/profiles/{id}/allowed-extensions`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a private plan's manager allow-list

`GET /api/v1/profiles/{id}/allowed-managers`

Which managers may see and assign this plan. Only meaningful while the plan is private; a public plan is visible to everyone regardless of this list.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |


### Replace a private plan's manager allow-list

`PUT /api/v1/profiles/{id}/allowed-managers`

Replaces the whole list. Managers omitted from the payload lose access.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |

#### Note

The allow-list is inert while private is false. Setting it on a public plan stores the rows and changes nothing, which looks exactly like the restriction failing to apply.


### Manage profile visibility / policy

`GET /api/v1/profiles/{id}/allowed-parents`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage profile visibility / policy

`PUT /api/v1/profiles/{id}/allowed-parents`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policy_manager` (Manage profile visibility / policy)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Clone a plan

`POST /api/v1/profiles/{id}/clone`

Copies the plan, including its RADIUS attributes and policies, under a new name. The usual way to build a variant without re-entering forty fields.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_create` (Create profiles)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan to copy. |


### Manage plan policy rules

`GET /api/v1/profiles/{id}/policies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policies` (Manage plan policy rules)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage plan policy rules

`POST /api/v1/profiles/{id}/policies`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policies` (Manage plan policy rules)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage plan policy rules

`POST /api/v1/profiles/{id}/policies/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policies` (Manage plan policy rules)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage plan policy rules

`DELETE /api/v1/profiles/{id}/policies/{policyID}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policies` (Manage plan policy rules)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage plan policy rules

`PATCH /api/v1/profiles/{id}/policies/{policyID}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_policies` (Manage plan policy rules)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Read a plan's per-reseller prices

`GET /api/v1/profiles/{id}/price-list`

The pricing-tree overrides for this plan: what each manager in the tree pays and may charge, where it differs from the plan default.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |


### Replace a plan's per-reseller prices

`PUT /api/v1/profiles/{id}/price-list`

Replaces the whole override set for this plan in one call. An entry omitted from the payload is removed, not left alone.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |

#### Note

A price cap of 0 and an absent cap mean different things. Absent is "no cap"; 0 is a cap of zero, which blocks every sale of that plan below the manager it is set on and reads on screen as "Over cap 0.00".


### List a plan's RADIUS attributes

`GET /api/v1/profiles/{id}/radius-attrs`

The reply attributes this plan adds to an Access-Accept, beyond the ones derived from its speed and quota settings.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_radius_attributes` (Manage RADIUS attributes)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |


### Add a RADIUS attribute to a plan

`POST /api/v1/profiles/{id}/radius-attrs`

Adds one reply attribute. Attributes set here ride on every session of every subscriber on the plan.

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_radius_attributes` (Manage RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Plan id. |


### Manage RADIUS attributes

`POST /api/v1/profiles/{id}/radius-attrs/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_radius_attributes` (Manage RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage RADIUS attributes

`DELETE /api/v1/profiles/{id}/radius-attrs/{attrId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_radius_attributes` (Manage RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage RADIUS attributes

`PATCH /api/v1/profiles/{id}/radius-attrs/{attrId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_radius_attributes` (Manage RADIUS attributes)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Auth

### GET /api/v1/auth/account

`GET /api/v1/auth/account`

- Authentication: manager session (JWT) or API token
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PATCH /api/v1/auth/account

`PATCH /api/v1/auth/account`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/2fa/disable

`POST /api/v1/auth/account/2fa/disable`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `account_reauth`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/2fa/enable

`POST /api/v1/auth/account/2fa/enable`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/2fa/recovery-codes

`POST /api/v1/auth/account/2fa/recovery-codes`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `account_reauth`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/2fa/setup

`POST /api/v1/auth/account/2fa/setup`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/avatar

`POST /api/v1/auth/account/avatar`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/auth/account/limits

`GET /api/v1/auth/account/limits`

- Authentication: manager session (JWT) or API token
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/password

`POST /api/v1/auth/account/password`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `account_reauth`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/auth/account/sessions

`GET /api/v1/auth/account/sessions`

- Authentication: manager session (JWT) or API token
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/account/sessions/revoke-others

`POST /api/v1/auth/account/sessions/revoke-others`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/auth/account/sessions/{jti}

`DELETE /api/v1/auth/account/sessions/{jti}`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Classify the host before signing in

`GET /api/v1/auth/context`

Tells a login page which flow to render: whether the host it was loaded on is a tenant subdomain, the instance apex, or unknown, plus the public tenant descriptor when it resolves. Unauthenticated, and always 200. It exposes only the public tenant slug, name and branding, and tenant is null for apex and unknown hosts.

- Authentication: none


### POST /api/v1/auth/impersonation/exit

`POST /api/v1/auth/impersonation/exit`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sign a manager in

`POST /api/v1/auth/login`

Exchanges an email or username and a password for a tenant-scoped session token. The tenant is taken from the host when you call a tenant subdomain, and a selector in the body is discarded in that case.

- Authentication: none
- Rate limit bucket: `login`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `email` | body | string | yes | Email or username. |
| `password` | body | string | yes | The manager's password. |
| `totp_code` | body | string | no | Six-digit code or a recovery code. Sent on the second attempt, after the first returns mfa_required. |
| `tenant_slug` | body | string | no | Honoured only when the host carries no tenant. Ignored outright on a tenant subdomain. |
| `refresh` | body | boolean | no | Opt in to the refresh-token flow. Omitting it returns one long-lived token and no refresh fields at all. |

#### Request

```json
{
  "email": "ops@acme.example",
  "password": "a-strong-password"
}
```

#### Response — 200 OK

```json
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user_id": 41,
    "tenant_id": 12,
    "tenant_slug": "acme",
    "roles": ["support"],
    "expires_at": 1758358800
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | the host carries no tenant and no selector was supplied — details.reason tenant_required |
| `ERR_UNAUTHORIZED` | 401 | wrong credentials (invalid_credentials), two-factor needed (mfa_required), or a bad code (mfa_invalid) |
| `ERR_RATE_LIMITED` | 429 | too many consecutive failures on this account — details.reason login_locked |
| `ERR_UNAVAILABLE` | 503 | the tenant's portal has been switched off — details.reason site_offline |

#### Note

mfa_required is a 401 with the same code as a wrong password. Branch on details.reason, never on the status or the message: six different login outcomes share ERR_UNAUTHORIZED and only the reason tells them apart. expires_at is unix SECONDS, not milliseconds and not a formatted timestamp.


### End the current session

`POST /api/v1/auth/logout`

Revokes the calling session's token id, so it stops working immediately rather than at expiry.

- Authentication: manager session (JWT) or API token
- Not available to API tokens: this route requires an interactive manager session

#### Response — 200 OK

```json
{
  "data": { "ok": true }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_FORBIDDEN` | 403 | the caller holds an API token — this route refuses machine credentials |

#### Note

Best-effort by design: it answers ok even if the revocation write failed, because the worst case is a token that dies at its natural expiry. Do not treat ok true as proof the token is dead.


### Who am I, and what may I do

`GET /api/v1/auth/me`

The one-shot bootstrap call: the current manager, their roles, the resolved permission codes, and the tenant settings a client needs before it can render anything. Authenticated but not permission-gated, so any working credential reaches it.

- Authentication: manager session (JWT) or API token

#### Response — 200 OK

```json
{
  "data": {
    "version": "0.2.34",
    "manager": {
      "id": 41,
      "tenant_id": 12,
      "email": "ops@acme.example",
      "username": "ops",
      "status": "active",
      "two_factor_enabled": true
    },
    "roles": ["support"],
    "permissions": ["prm_users_index", "prm_users_update"],
    "is_admin": false,
    "settings": {
      "currency": "EGP",
      "timezone": "Africa/Cairo",
      "default_language": "en",
      "pos_undo_window_seconds": 60
    },
    "tenant": {
      "license_status": "active",
      "license_expires_at": "2027-01-31 00:00:00",
      "max_users": 5000,
      "users_count": 812,
      "blocked": false,
      "blocked_reason": ""
    }
  }
}
```

#### Note

For an API token, permissions is the INTERSECTION of the token's scope with its owner's live permissions, and is_admin is forced to false even when the owner is a tenant administrator. That is the authoritative answer to what the credential may do — gate your client on this array, not on the owner's role names. max_users null means unlimited; 0 means blocked, not unlimited.


### DELETE /api/v1/auth/push-tokens

`DELETE /api/v1/auth/push-tokens`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/push-tokens

`POST /api/v1/auth/push-tokens`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Exchange a refresh token

`POST /api/v1/auth/refresh`

Issues a new session token from a refresh token. Only available when the original login asked for one.

- Authentication: none
- Rate limit bucket: `refresh`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `refresh_token` | body | string | yes | The refresh token returned by login. Shown once; only its hash is stored. |

#### Request

```json
{
  "refresh_token": "wA7k2Jd9..."
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_UNAUTHORIZED` | 401 | the session was signed out (session_revoked), or the token is unknown or expired (invalid_credentials) |

#### Note

An expired refresh token and an unknown one answer identically, on purpose. A revoked session is the one case that is distinguished, because the remedy differs: sign in again rather than retry.


### POST /api/v1/auth/register/complete

`POST /api/v1/auth/register/complete`

- Authentication: none
- Rate limit bucket: `register_complete`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/register/resend

`POST /api/v1/auth/register/resend`

- Authentication: none
- Rate limit bucket: `register_resend`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/register/start

`POST /api/v1/auth/register/start`

- Authentication: none
- Rate limit bucket: `register_start`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/auth/register/verify

`POST /api/v1/auth/register/verify`

- Authentication: none
- Rate limit bucket: `register_verify`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Reports

### Activation statistics report

`GET /api/v1/admin/reports/activation-stats`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_activation_stats` (Activation statistics report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Activations report

`GET /api/v1/admin/reports/activations`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_activations` (Activations report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Cards log report

`GET /api/v1/admin/reports/cards-transfer`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_cards_log` (Cards log report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Cards usage report

`GET /api/v1/admin/reports/cards-usage`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_cards_usage` (Cards usage report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debts journal report

`GET /api/v1/admin/reports/claims-managers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_debts` (Debts journal report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debts journal report

`GET /api/v1/admin/reports/debtors-managers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_debts` (Debts journal report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debts journal report

`GET /api/v1/admin/reports/debtors-users`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_debts` (Debts journal report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Debts journal report

`GET /api/v1/admin/reports/debts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_debts` (Debts journal report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/reports/gateway-txns

`GET /api/v1/admin/reports/gateway-txns`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_report_gateway_transactions`, `prm_report_gateway_transactions_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View manager invoices

`GET /api/v1/admin/reports/manager-invoices`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_invoices` (View manager invoices)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View manager journal

`GET /api/v1/admin/reports/manager-journal`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_journal` (View manager journal)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View manager receipts

`GET /api/v1/admin/reports/manager-receipts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_receipts` (View manager receipts)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Money transfer report

`GET /api/v1/admin/reports/money-transfer`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_money_transfer` (Money transfer report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Profits report

`GET /api/v1/admin/reports/profits`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_profits` (Profits report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sessions report

`GET /api/v1/admin/reports/sessions`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_sessions` (Sessions report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Suspicious users report

`GET /api/v1/admin/reports/suspicious`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_suspicious` (Suspicious users report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Traffic report

`GET /api/v1/admin/reports/traffic`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_traffic` (Traffic report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Users report

`GET /api/v1/admin/reports/users`

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_users` (Users report)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Studio

### View designs

`GET /api/v1/studio/designs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and edit designs

`POST /api/v1/studio/designs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_edit` (Create and edit designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete designs

`POST /api/v1/studio/designs/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_delete` (Delete designs)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete designs

`DELETE /api/v1/studio/designs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_delete` (Delete designs)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/designs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and edit designs

`PATCH /api/v1/studio/designs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_edit` (Create and edit designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/designs/{id}/thumbnail`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/store`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Publish designs to the store

`POST /api/v1/studio/store`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_publish` (Publish designs to the store)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/store/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/store/{id}/comments`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`POST /api/v1/studio/store/{id}/comments`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and edit designs

`POST /api/v1/studio/store/{id}/import`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_edit` (Create and edit designs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/store/{id}/reviews`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`POST /api/v1/studio/store/{id}/reviews`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`DELETE /api/v1/studio/store/{id}/star`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`POST /api/v1/studio/store/{id}/star`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View designs

`GET /api/v1/studio/store/{id}/thumbnail`

- Authentication: manager session (JWT) or API token
- Permission: `prm_studio_index` (View designs)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Payments

### List configured gateways

`GET /api/v1/admin/payments/config`

Just the tenant's configured rows, with credentials masked, for a page that already holds the catalogue.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger


### Configure a gateway

`POST /api/v1/admin/payments/config`

Upserts one gateway's credentials and settings. Every field is keep-existing, so a partial payload leaves unsent credentials alone rather than clearing them.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | body | string | yes | Driver id from the catalogue. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown gateway id, or a field the driver does not accept |


### Remove a gateway configuration

`DELETE /api/v1/admin/payments/config/{gateway}`

Deletes the tenant's credentials for one driver. Transactions already recorded against it are untouched.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Update one gateway's configuration

`PATCH /api/v1/admin/payments/config/{gateway}`

The same upsert as the POST, with the gateway named in the path. The PATH wins over any gateway field in the body, so a stale client cannot retarget an edit at a different gateway.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Test a gateway configuration

`POST /api/v1/admin/payments/config/{gateway}/test`

Checks the stored credentials against the provider.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Read a gateway's callback URL

`GET /api/v1/admin/payments/config/{gateway}/webhook-url`

The exact URL to register with the provider, including the per-tenant secret path segment. Copy it verbatim.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |

#### Note

The URL contains a secret. It is what proves an inbound callback came from the provider you configured, so treat the response as a credential and do not paste it into a ticket.


### Top up own wallet online

`POST /api/v1/admin/payments/deposit`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_self_deposit` (Top up own wallet online)
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Top up own wallet online

`GET /api/v1/admin/payments/deposit/gateways`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_self_deposit` (Top up own wallet online)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List the gateway catalogue and what is configured

`GET /api/v1/admin/payments/gateways`

The drivers this build supports, the tenant's own configured rows with secrets masked, and the public base URL a gateway should call back to.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

#### Response — 200 OK

```json
{
  "data": {
    "catalog": [
      {
        "id": "paymob",
        "label": "Paymob",
        "methods": [],
        "fields": [],
        "ttl_seconds": 900,
        "min_amount": 0,
        "implemented": true,
        "pollable": true
      }
    ],
    "configured": [],
    "public_base_url": "https://acme.example.com"
  }
}
```

#### Note

Read implemented and pollable before building against a driver. implemented false is a registry stub whose vendor contract is not verified; pollable false means the gateway has no merchant-readable status API, so its callback is the only channel and a lost callback is a lost payment. min_amount is the PSP's own floor in major units, and 0 means no floor.


### GET /api/v1/admin/payments/transactions/{id}

`GET /api/v1/admin/payments/transactions/{id}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_report_gateway_transactions`, `prm_report_gateway_transactions_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Re-check and write off gateway transactions

`POST /api/v1/admin/payments/transactions/{id}/recheck`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_manage` (Re-check and write off gateway transactions)
- Risk: write
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Mark gateway payments paid / refunded (moves money)

`POST /api/v1/admin/payments/transactions/{id}/refund`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_settle` (Mark gateway payments paid / refunded (moves money))
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Mark gateway payments paid / refunded (moves money)

`POST /api/v1/admin/payments/transactions/{id}/settle`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_settle` (Mark gateway payments paid / refunded (moves money))
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Re-check and write off gateway transactions

`POST /api/v1/admin/payments/transactions/{id}/status`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_manage` (Re-check and write off gateway transactions)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Freezone

### Manage Free Zone networks

`GET /api/v1/freezone/preview-address-list`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`POST /api/v1/freezone/push`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`GET /api/v1/freezone/router-script`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`GET /api/v1/freezone/zones`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`POST /api/v1/freezone/zones`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`POST /api/v1/freezone/zones/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`DELETE /api/v1/freezone/zones/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`PATCH /api/v1/freezone/zones/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`GET /api/v1/freezone/zones/{id}/entries`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`POST /api/v1/freezone/zones/{id}/entries`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`POST /api/v1/freezone/zones/{id}/entries/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage Free Zone networks

`DELETE /api/v1/freezone/zones/{id}/entries/{entryId}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_freezone_manage` (Manage Free Zone networks)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## POS

### Sell cards at the counter (till)

`GET /api/v1/pos/products`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`GET /api/v1/pos/sales`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`POST /api/v1/pos/sales`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`GET /api/v1/pos/sales/{id}/print-job`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`POST /api/v1/pos/sales/{id}/printed`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/pos/sales/{id}/void

`POST /api/v1/pos/sales/{id}/void`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_pos_sell`, `prm_pos_void`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`GET /api/v1/pos/shifts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`POST /api/v1/pos/shifts`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`GET /api/v1/pos/shifts/current`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`POST /api/v1/pos/shifts/{id}/close`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Sell cards at the counter (till)

`GET /api/v1/pos/shifts/{id}/report`

- Authentication: manager session (JWT) or API token
- Permission: `prm_pos_sell` (Sell cards at the counter (till))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Sessions

### List live sessions

`GET /api/v1/admin/sessions`

Sessions with no stop time, paginated with the standard list parameters. A non-admin caller sees only sessions belonging to their own manager subtree, injected server-side.

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_sessions` (Sessions report)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | no | Searches username, first and last name, framed IP, device MAC and NAS name. |
| `filter[nas_id]` | query | integer | no | Sessions on one registered NAS. |
| `filter[kind]` | query | enum | no | subscriber, guest, voucher or unknown. |
| `filter[has_ip]` | query | boolean | no | Sessions that were assigned a framed IP. |
| `filter[duration_band]` | query | string | no | Duration bucket. The value "stale" means no accounting update for longer than the tenant's idle window, which is the practical definition of a ghost session. |
| `filter[expired]` | query | boolean | no | Sessions whose owner's subscription has run out but who are still connected. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 8821904,
      "acct_session_id": "81b0c4e2",
      "username": "ahmed",
      "user_id": 4711,
      "kind": "subscriber",
      "nas_ip": "10.20.0.1",
      "nas_id": 3,
      "nas_name": "cairo-edge-1",
      "vendor": "mikrotik",
      "framed_ip": "10.64.12.51",
      "calling_station_id": "AA:BB:CC:DD:EE:FF",
      "start_time": "2026-09-20 07:11:02",
      "update_time": "2026-09-20 09:06:02",
      "session_time": 6900,
      "input_octets": 412000000,
      "output_octets": 5100000000,
      "profile_name": "Home 20M",
      "usage": { "percent": 55.0, "dimension": "data" }
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 318, "has_next": true }
}
```

#### Note

user_id is null for a session this instance cannot tie to a subscriber row, such as an anonymous voucher or an orphan left by a NAS restart. status and usage are absent on those too. Do not assume every live session has an owner.


### Disconnect many sessions

`POST /api/v1/admin/sessions/bulk-disconnect`

Sends a Disconnect-Request per session id and reports the per-id outcome. One request against the write budget rather than one per session.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_live_traffic` (Live traffic / disconnect)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ids` | body | array | yes | Session ids. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_INTERNAL` | 503 | no CoA dispatcher is wired |

#### Note

The same NAS-accepted-it caveat as the single disconnect applies to every id in the report, and the partial-failure envelope means a 200 does not mean all of them were sent.


### Lock user MAC

`POST /api/v1/admin/sessions/bulk-lock-mac`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_mac_lock` (Lock user MAC)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Ping user

`POST /api/v1/admin/sessions/bulk-ping`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_ping` (Ping user)
- Risk: read
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Fetch one live session

`GET /api/v1/admin/sessions/{id}`

One session with the full projection, including the joined subscriber attributes.

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_sessions` (Sessions report)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | The accounting row id, not the subscriber id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such session, or one outside the caller's subtree |


### Disconnect a session

`POST /api/v1/admin/sessions/{id}/disconnect`

Sends an RFC 5176 Disconnect-Request straight from this platform to the NAS that owns the session. The packet goes out over UDP to the device, not through the RADIUS server.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_live_traffic` (Live traffic / disconnect)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Session id. |

#### Response — 200 OK

```json
{
  "data": { "ok": true, "nak": false, "message": "disconnected" }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such session, or one outside the caller's subtree |
| `ERR_INTERNAL` | 502 | the NAS did not answer, or the exchange failed. details.reason carries the transport error |
| `ERR_INTERNAL` | 503 | no CoA dispatcher is wired in this deployment |

#### Note

ok true means the NAS ACCEPTED the packet, not that the subscriber is off the network. Whether the session actually ends is up to the device, and it will be reflected in accounting a moment later. nak true is also a success from your point of view: the NAS replied "no such session", so it is already gone. Only a 502 means the disconnect did not happen.


### Read near-real-time throughput

`GET /api/v1/admin/sessions/{id}/live-traffic`

Returns bits per second when the session's NAS has SNMP management credentials with an interface selector configured, by polling the device twice about a second apart. Without them it degrades to the accounting counters.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_live_traffic` (Live traffic / disconnect)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Session id. |

#### Note

Check the source field before trusting the numbers. source "snmp" is a real measurement; source "interim" means there were no SNMP credentials, the device was unreachable, or the sampler is not wired — the counters are the last accounting values and bps is 0, and your client has to derive the rate from successive polls itself.


### Live traffic / disconnect

`GET /api/v1/admin/sessions/{id}/live-traffic/stream`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_live_traffic` (Live traffic / disconnect)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Bind the subscriber to this session's device

`POST /api/v1/admin/sessions/{id}/lock-mac`

Writes the session's calling-station MAC into the subscriber's locked-MAC list. From the next authentication onward only that device may connect. The current session is left up, since it already uses the locked MAC.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_mac_lock` (Lock user MAC)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Session id. |

#### Response — 200 OK

```json
{
  "data": {
    "user_id": 4711,
    "mac": "AA:BB:CC:DD:EE:FF",
    "locked_macs": ["AA:BB:CC:DD:EE:FF"]
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 422 | the session has no owning subscriber, so there is no record to lock |

#### Note

This endpoint also turns the lock ON, which the subscriber PATCH does not. Writing mac_locked_addrs through PATCH /users/{id} without setting mac_lock_enabled stores a list that enforces nothing.


### Ping the subscriber's device

`POST /api/v1/admin/sessions/{id}/ping`

Sends ICMP echo to the session's framed IP from the platform. An operator diagnostic, not a monitoring feed.

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_ping` (Ping user)
- Risk: read
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Session id. |

#### Note

On the per-tenant probe budget, which is 10 a minute on a standard licence. It is sized for an operator clicking a button; a polling loop will exhaust it in six seconds and take every other probe endpoint down with it.


### Poll a session's counters

`GET /api/v1/admin/sessions/{id}/traffic`

The lightweight counter snapshot behind a live traffic graph. It is a snapshot, not a rate — derive throughput from the difference between two polls and the difference between their sampled_at stamps.

- Authentication: manager session (JWT) or API token
- Permission: `prm_report_sessions` (Sessions report)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Session id. |

#### Response — 200 OK

```json
{
  "data": {
    "id": 8821904,
    "session_time": 6900,
    "input_octets": 412000000,
    "output_octets": 5100000000,
    "update_time": "2026-09-20 09:06:02",
    "sampled_at": "2026-09-20 09:08:31"
  }
}
```

#### Note

update_time is when the NAS last reported, and sampled_at is when this server read it. They differ by up to one accounting interval, so two polls closer together than that interval return identical counters and a throughput of zero. That is the NAS being quiet, not the subscriber.



## Cards

### Redeem a card over the counter

`POST /api/v1/admin/cards/redeem-otc`

The same operation as the subscriber-facing redeem, with one difference: the acting manager is recorded as the reseller, so the redemption snapshots what they paid against what they charged. Without that, per-reseller pricing never resolves and every redemption records face value on both sides.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_verify` (Verify / redeem cards)
- Risk: write
- Rate limit bucket: `card_redeem`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | body | string | yes | The plaintext card code. |
| `user_id` | body | integer | yes | The subscriber to credit. |
| `request_id` | body | string | yes | Idempotency key. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | unknown code, or a card or subscriber outside the caller's authority |
| `ERR_CONFLICT` | 409 | already redeemed, or a request_id bound to another card |


### Top up own wallet online

`POST /api/v1/admin/cards/redeem-to-wallet`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_self_deposit` (Top up own wallet online)
- Risk: danger
- Rate limit bucket: `card_wallet_redeem`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View card batches & cards

`GET /api/v1/admin/cards/redemptions/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View card batches & cards

`GET /api/v1/admin/cards/redemptions/{id}/reversals`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Refund last activation

`POST /api/v1/admin/cards/redemptions/{id}/reversals`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_refund` (Refund last activation)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Redeem a card onto a subscriber

`POST /api/v1/cards/redeem`

Spends a card and applies its effect to the named subscriber. Two authority checks run, both derived from your credential and neither from the body: the card must be in your subtree, and the subscriber must be one you may write to. Both denials are 404s identical to "no such card" and "no such subscriber".

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_verify` (Verify / redeem cards)
- Risk: write
- Rate limit bucket: `card_redeem`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | body | string | yes | The plaintext card code. |
| `user_id` | body | integer | yes | The subscriber to credit. |
| `request_id` | body | string | yes | Idempotency key. |

#### Request

```json
{
  "code": "K7P4M2Q9XD",
  "user_id": 4711,
  "request_id": "3a1d0c77-8b52-4e19-9d64-1f7e2c5a9b30"
}
```

#### Response — 200 OK

```json
{
  "data": {
    "card_id": 90211,
    "mode": "refill_balance",
    "user_id": 4711,
    "effect_applied": { "type": "add_balance", "amount": 150.00 },
    "new_balance": 400.00
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | code, user_id or request_id missing, or a reserved or over-long request_id |
| `ERR_NOT_FOUND` | 404 | unknown code, a card outside your subtree, or a subscriber you may not write to |
| `ERR_CONFLICT` | 409 | the card is already redeemed, or the request_id belongs to a redemption of a different card |
| `ERR_CONFLICT` | 410 | the card has been revoked or has expired |

#### Note

A replay returns 200 with the same card_id, mode and effect_applied, and NO replay flag — but new_balance is ABSENT, because the replay path returns the stored effect without re-reading the wallet. A missing new_balance is not a failure and is not a reason to retry. Read the balance off the subscriber record if you need it.


### POST /api/v1/cards/redeem-create

`POST /api/v1/cards/redeem-create`

- Authentication: none
- Rate limit bucket: `card_redeem`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Verify one card by code, serial or username

`GET /api/v1/cards/search`

The counter-staff lookup. Finds a single card and reports its state, its owning reseller and who spent it. Confined to the caller's manager subtree unless they are an administrator.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_verify` (Verify / redeem cards)
- Risk: write
- Rate limit bucket: `card_search`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | enum | yes | code, serial or username. |
| `keyword` | query | string | yes | The value to match. A code is normalised first, so separators and mixed case still resolve. |

#### Response — 200 OK

```json
{
  "data": {
    "card_id": 90211,
    "serial": "000312",
    "state": "consumed",
    "effective_state": "consumed",
    "disposition": "",
    "mode": "voucher_account",
    "plan_name": "Home 20M",
    "batch_id": 208,
    "face_value": 150.00,
    "redemptions_left": 0,
    "owner_manager_id": 41,
    "owner_username": "cairo-reseller",
    "used_by_kind": "user",
    "used_by_user_id": 4711,
    "used_by_username": "ahmed",
    "used_channel": "customer_portal",
    "first_use_at": "2026-09-14 18:22:10",
    "expires_at": "2027-01-01 00:00:00"
  }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no card matches, or the card is outside the caller's subtree |

#### Note

A card outside your subtree answers the same 404 as an unknown keyword, never a 403 — a 403 would confirm the code exists and turn this into a code-guessing oracle. It carries its own per-operator budget for the same reason, separate from the tenant's.


### Revoke one card

`POST /api/v1/cards/{id}/revoke`

Flips a single card to revoked. A revoked card can never be redeemed, and the state is terminal.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_suspend_release` (Suspend / release cards)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Card id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such card, or one outside the caller's subtree |
| `ERR_CONFLICT` | 409 | the card is already in a terminal state |


### One card's full lifecycle

`GET /api/v1/cards/{id}/timeline`

Header facts plus the chronological event list for a single card: when it was minted, printed, sold, transferred and redeemed.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read
- Rate limit bucket: `card_timeline`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Card id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such card, or one outside the caller's subtree |

#### Note

This endpoint's rate-limit bucket counts DENIED lookups too, on purpose. The limiter sits ahead of the visibility check, so a walk of the card id space burns budget rather than running unmetered behind a 404.



## Developer

### View and revoke ALL API tokens in this tenant

`GET /api/v1/developer/admin/api-tokens`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens_all` (View and revoke ALL API tokens in this tenant)
- Risk: danger
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View and revoke ALL API tokens in this tenant

`DELETE /api/v1/developer/admin/api-tokens/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens_all` (View and revoke ALL API tokens in this tenant)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`GET /api/v1/developer/api-tokens`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`POST /api/v1/developer/api-tokens`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`GET /api/v1/developer/api-tokens/scopes`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`DELETE /api/v1/developer/api-tokens/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`PATCH /api/v1/developer/api-tokens/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`DELETE /api/v1/developer/api-tokens/{id}/record`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`POST /api/v1/developer/api-tokens/{id}/reveal`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `api_token_reveal`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create and manage my API tokens

`POST /api/v1/developer/api-tokens/{id}/roll`

- Authentication: manager session (JWT) or API token
- Permission: `prm_api_tokens` (Create and manage my API tokens)
- Risk: danger
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Devgw

### CONNECT /api/v1/admin/devgw/ssh/ws

`CONNECT /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/admin/devgw/ssh/ws

`DELETE /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/devgw/ssh/ws

`GET /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### HEAD /api/v1/admin/devgw/ssh/ws

`HEAD /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### OPTIONS /api/v1/admin/devgw/ssh/ws

`OPTIONS /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PATCH /api/v1/admin/devgw/ssh/ws

`PATCH /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/devgw/ssh/ws

`POST /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/admin/devgw/ssh/ws

`PUT /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### QUERY /api/v1/admin/devgw/ssh/ws

`QUERY /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### TRACE /api/v1/admin/devgw/ssh/ws

`TRACE /api/v1/admin/devgw/ssh/ws`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Hotspot

### Manage hotspot pages

`GET /api/v1/hotspot/pages`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`POST /api/v1/hotspot/pages`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`POST /api/v1/hotspot/pages/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`DELETE /api/v1/hotspot/pages/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`GET /api/v1/hotspot/pages/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`PATCH /api/v1/hotspot/pages/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`GET /api/v1/hotspot/pages/{id}/download`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`POST /api/v1/hotspot/pages/{id}/duplicate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`POST /api/v1/hotspot/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage hotspot pages

`GET /api/v1/hotspot/templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_hotspot_manage` (Manage hotspot pages)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Card Templates

### GET /api/v1/card-templates

`GET /api/v1/card-templates`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_card_templates_index`, `prm_card_templates_index_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create / edit card templates

`POST /api/v1/card-templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_manage` (Create / edit card templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create / edit card templates

`POST /api/v1/card-templates/from-batch`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_manage` (Create / edit card templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete card templates

`DELETE /api/v1/card-templates/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_delete` (Delete card templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/card-templates/{id}

`GET /api/v1/card-templates/{id}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_card_templates_index`, `prm_card_templates_index_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create / edit card templates

`PATCH /api/v1/card-templates/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_manage` (Create / edit card templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Generate user cards

`POST /api/v1/card-templates/{id}/generate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_generate_user` (Generate user cards)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Share card templates (public / allow-list)

`GET /api/v1/card-templates/{id}/sharing`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_share` (Share card templates (public / allow-list))
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Share card templates (public / allow-list)

`PUT /api/v1/card-templates/{id}/sharing`

- Authentication: manager session (JWT) or API token
- Permission: `prm_card_templates_share` (Share card templates (public / allow-list))
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## IP Pools

### View IP pools

`GET /api/v1/ip-pools`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_view` (View IP pools)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage IP pools

`POST /api/v1/ip-pools`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_manage` (Manage IP pools)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage IP pools

`POST /api/v1/ip-pools/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_manage` (Manage IP pools)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View IP pools

`GET /api/v1/ip-pools/names`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_view` (View IP pools)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage IP pools

`DELETE /api/v1/ip-pools/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_manage` (Manage IP pools)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View IP pools

`GET /api/v1/ip-pools/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_view` (View IP pools)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage IP pools

`PATCH /api/v1/ip-pools/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_manage` (Manage IP pools)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View IP pools

`GET /api/v1/ip-pools/{id}/leases`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_view` (View IP pools)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage IP pools

`POST /api/v1/ip-pools/{id}/leases/{leaseId}/release`

- Authentication: manager session (JWT) or API token
- Permission: `prm_ippool_manage` (Manage IP pools)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Shop

### Publish / unpublish card series to the shop

`POST /api/v1/admin/shop/batches/bulk-publish`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_publish` (Publish / unpublish card series to the shop)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Publish / unpublish card series to the shop

`POST /api/v1/admin/shop/batches/{id}/publish`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_publish` (Publish / unpublish card series to the shop)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Publish / unpublish card series to the shop

`POST /api/v1/admin/shop/batches/{id}/unpublish`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_publish` (Publish / unpublish card series to the shop)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View the Card Shop

`GET /api/v1/admin/shop/readiness`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_index` (View the Card Shop)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/shop/sales

`GET /api/v1/admin/shop/sales`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_shop_sales`, `prm_shop_sales_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/shop/sales/{id}

`GET /api/v1/admin/shop/sales/{id}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_shop_sales`, `prm_shop_sales_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/shop/sales/{id}/resend

`POST /api/v1/admin/shop/sales/{id}/resend`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_shop_sales`, `prm_shop_sales_all`
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Reveal a shop buyer's name and phone

`POST /api/v1/admin/shop/sales/{id}/reveal`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_buyer_contact` (Reveal a shop buyer's name and phone)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View the Card Shop

`GET /api/v1/admin/shop/storefront`

- Authentication: manager session (JWT) or API token
- Permission: `prm_shop_index` (View the Card Shop)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Webhooks

### Read the delivery log

`GET /api/v1/admin/webhooks/deliveries`

One page of delivery attempts, newest first, without the payload bodies. This is where you diagnose an integration that is not receiving events.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[endpoint_id]` | query | integer | no | Narrow to one endpoint. Also accepted as a bare endpoint_id parameter. |
| `filter[state]` | query | enum | no | queued, sending, sent, failed or dead. An unknown value is a 400. |
| `sort` | query | string | no | queued_at, state, attempts or id. Defaults to queued_at descending. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 77120,
      "endpoint_id": 4,
      "event_type": "user.created",
      "state": "failed",
      "attempts": 3,
      "max_attempts": 6,
      "response_code": 502,
      "response_ms": 1204,
      "last_error": "upstream returned 502",
      "url": "https://hooks.acme.example/xradius",
      "queued_at": "2026-09-20 09:00:00",
      "sent_at": "2026-09-20 09:04:11",
      "next_attempt_at": "2026-09-20 09:20:00"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 4102, "has_next": true }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown state filter, or a non-numeric endpoint_id |

#### Note

failed and dead are different. failed means it will be retried, and next_attempt_at says when; dead means the attempt budget is spent and nothing further will happen without a replay. An integration that went quiet has rows in dead, not failed.


### Replay a delivery

`POST /api/v1/admin/webhooks/deliveries/{id}/replay`

Re-queues a past delivery, which is how a dead one is recovered after the receiving side is fixed.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_egress`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Delivery id. |

#### Note

Your receiver will see the same event twice if the original eventually landed. Webhook receivers have to be idempotent on the event id; this endpoint is one of the reasons why.


### List webhook endpoints

`GET /api/v1/admin/webhooks/endpoints`

Every configured endpoint for the tenant, with its subscription set. Un-paginated: the whole set is page 1 and has_next is always false.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 4,
      "name": "billing-sync",
      "url": "https://hooks.acme.example/xradius",
      "events": ["user.created", "user.disconnected"],
      "all_events": false,
      "enabled": true,
      "created_at": "2026-06-11 14:20:00",
      "updated_at": "2026-09-02 08:31:12"
    }
  ],
  "meta": { "page": 1, "page_size": 1, "total": 1, "has_next": false }
}
```


### Create a webhook endpoint

`POST /api/v1/admin/webhooks/endpoints`

Registers a URL and the events it should receive. Set all_events to subscribe to everything, present and future, instead of naming keys.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | body | string | yes | A label for the endpoint. |
| `url` | body | string | yes | Where deliveries are POSTed. Validated on save. |
| `events` | body | array | no | Event keys from the catalogue. Ignored when all_events is true. |
| `all_events` | body | boolean | no | Subscribe to every event, including ones added in later releases. |
| `enabled` | body | boolean | no | Defaults to true on create. |

#### Request

```json
{
  "name": "billing-sync",
  "url": "https://hooks.acme.example/xradius",
  "events": ["user.created", "user.disconnected"],
  "all_events": false,
  "enabled": true
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown event key, or a URL that does not validate |
| `ERR_CONFLICT` | 409 | the licensed endpoint ceiling is reached |

#### Note

Answers 200, not 201, despite creating a record. Do not gate your client on the status code here.


### Manage notification channels & templates

`POST /api/v1/admin/webhooks/endpoints/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a webhook endpoint

`DELETE /api/v1/admin/webhooks/endpoints/{id}`

Removes the endpoint. Queued deliveries for it stop.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Endpoint id. |


### Update a webhook endpoint

`PATCH /api/v1/admin/webhooks/endpoints/{id}`

Replaces name, url, events and all_events outright, and patches enabled only when it is present. Send the full object, because a missing events array clears the subscription rather than leaving it alone.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Endpoint id. |

#### Note

This is a PATCH that behaves as a replace for four of its five fields. An update that sends only url wipes the events list.


### Send a test delivery

`POST /api/v1/admin/webhooks/endpoints/{id}/test`

Queues one synthetic delivery to the endpoint and returns its id so you can follow it in the log.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_egress`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Endpoint id. |

#### Response — 200 OK

```json
{
  "data": { "delivery_id": 77120 }
}
```

#### Note

The delivery is QUEUED, not sent. A 200 here says the job was created, not that your endpoint answered. Poll the delivery log for the outcome. It is also on the per-tenant egress budget, which is 5 a minute on a standard licence.


### List subscribable event keys

`GET /api/v1/admin/webhooks/event-catalog`

Every event an endpoint may subscribe to, with its category. The create and update endpoints validate the events array against exactly this set, so read it before writing one. Static for the life of the release, so fetch it once and cache it.

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

#### Response — 200 OK

```json
{
  "data": [
    { "key": "user.created", "category": "lifecycle" },
    { "key": "user.disconnected", "category": "lifecycle" },
    { "key": "usage.threshold", "category": "usage" }
  ],
  "meta": { "page": 1, "page_size": 3, "total": 3, "has_next": false }
}
```



## Addons

### Sell add-ons

`GET /api/v1/addons`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_addon` (Sell add-ons)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View add-ons

`GET /api/v1/admin/addons`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_index` (View add-ons)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage add-ons

`POST /api/v1/admin/addons`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_manage` (Manage add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage add-ons

`POST /api/v1/admin/addons/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_manage` (Manage add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage add-ons

`DELETE /api/v1/admin/addons/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_manage` (Manage add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage add-ons

`PATCH /api/v1/admin/addons/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_manage` (Manage add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View add-ons

`GET /api/v1/admin/addons/{id}/allowed-profiles`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_index` (View add-ons)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage add-ons

`PUT /api/v1/admin/addons/{id}/allowed-profiles`

- Authentication: manager session (JWT) or API token
- Permission: `prm_addons_manage` (Manage add-ons)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Dashboards

### GET /api/v1/admin/dashboards/me

`GET /api/v1/admin/dashboards/me`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_values`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/admin/dashboards/me/appearance

`PUT /api/v1/admin/dashboards/me/appearance`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/admin/dashboards/me/customize

`DELETE /api/v1/admin/dashboards/me/customize`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### PUT /api/v1/admin/dashboards/me/customize

`PUT /api/v1/admin/dashboards/me/customize`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/dashboards/me/designed

`GET /api/v1/admin/dashboards/me/designed`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/dashboards/me/tiles/{id}

`GET /api/v1/admin/dashboards/me/tiles/{id}`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_values`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/dashboards/me/values

`GET /api/v1/admin/dashboards/me/values`

- Authentication: manager session (JWT) or API token
- Rate limit bucket: `t_values`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View support tickets

`GET /api/v1/admin/dashboards/support`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tickets_view` (View support tickets)
- Risk: read
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Forms

### Manage custom form fields

`GET /api/v1/admin/forms`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage custom form fields

`POST /api/v1/admin/forms`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage custom form fields

`POST /api/v1/admin/forms/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create users

`GET /api/v1/admin/forms/manifest`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_create` (Create users)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage custom form fields

`POST /api/v1/admin/forms/reorder`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create users

`GET /api/v1/admin/forms/{form_name}/schema`

- Authentication: manager session (JWT) or API token
- Permission: `prm_users_create` (Create users)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage custom form fields

`DELETE /api/v1/admin/forms/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage custom form fields

`PATCH /api/v1/admin/forms/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_forms_manage` (Manage custom form fields)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Sas4

### Export SAS4 backup

`GET /api/v1/admin/sas4/export`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_export` (Export SAS4 backup)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`GET /api/v1/admin/sas4/import/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`POST /api/v1/admin/sas4/import/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`POST /api/v1/admin/sas4/import/jobs/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`DELETE /api/v1/admin/sas4/import/jobs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`GET /api/v1/admin/sas4/import/jobs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`POST /api/v1/admin/sas4/import/jobs/{id}/cancel`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import SAS4 backup

`POST /api/v1/admin/sas4/import/jobs/{id}/start`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_sas4_import` (Import SAS4 backup)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Backup

### Manage settings

`GET /api/v1/admin/backup/destinations`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`PATCH /api/v1/admin/backup/destinations`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/admin/backup/destinations`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`DELETE /api/v1/admin/backup/destinations/{provider}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/admin/backup/destinations/{provider}/connect`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/admin/backup/destinations/{provider}/test`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_probe`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`GET /api/v1/admin/backup/remote-types`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Control

### POST /api/v1/control/managers/2fa-reset

`POST /api/v1/control/managers/2fa-reset`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/control/ping

`GET /api/v1/control/ping`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/control/registrations

`GET /api/v1/control/registrations`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/control/registrations/{public_id}/approve

`POST /api/v1/control/registrations/{public_id}/approve`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/control/registrations/{public_id}/reject

`POST /api/v1/control/registrations/{public_id}/reject`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/control/sync

`POST /api/v1/control/sync`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/control/sysbackup/ticket

`POST /api/v1/control/sysbackup/ticket`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Exports

### List export jobs

`GET /api/v1/exports`

Jobs the caller owns, with their progress. A non-admin sees only jobs from their own manager subtree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_index` (View export jobs)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[status]` | query | string | no | Job status. |
| `filter[format]` | query | enum | no | csv or xlsx. |
| `filter[target_table]` | query | string | no | One dataset key. The special value "reports" expands to every report dataset rather than matching exactly. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 3312,
      "target_table": "users",
      "format": "xlsx",
      "status": "running",
      "processed": 4200,
      "total": 8120,
      "row_count": 0,
      "manager_id": 41,
      "created_at": "2026-09-20 09:10:00",
      "started_at": "2026-09-20 09:10:04"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 12, "has_next": false }
}
```


### Queue an export

`POST /api/v1/exports`

Creates the job and returns immediately; a separate worker produces the file. The caller's authority scope is stamped onto the job server-side, so an export contains exactly what that manager's list view would show and nothing more.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_create` (Create / delete export jobs)
- Risk: write
- Rate limit bucket: `t_heavy`
- Idempotent on `request_id`: retrying with the same id returns the original result

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `target_table` | body | string | yes | A dataset key from the datasets endpoint. |
| `format` | body | enum | no | csv or xlsx. Defaults to xlsx. |
| `params` | body | object | no | Dataset-specific filters, in the same shape that dataset's list endpoint accepts. |
| `request_id` | body | string | no | Optional idempotency key. Blank stays blank and means no deduplication at all — supply your own if a retry must not queue a second job. |

#### Request

```json
{
  "target_table": "users",
  "format": "xlsx",
  "params": { "enabled": true },
  "request_id": "9d41f0c2-6b17-4e58-93a2-8c0e5f7b1d34"
}
```

#### Response — 202 Accepted

```json
{
  "data": { "id": 3312 }
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown target_table, or a format that is neither csv nor xlsx |
| `ERR_FORBIDDEN` | 403 | the caller may create exports but lacks the permission to VIEW that table |

#### Note

Exporting a table needs the permission to read it as well as the permission to export. The route's own gate is not enough, so a role with export rights but no subscriber-read right gets a 403 on target_table users. That is the check that stops an export from being a way around a list permission.


### Create / delete export jobs

`POST /api/v1/exports/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_create` (Create / delete export jobs)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List exportable datasets

`GET /api/v1/exports/datasets`

Every table this build can export, with its key. target_table on the enqueue call must be one of these, and an unknown value is a 400. Static for the life of the release, so fetch it once and cache it.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_index` (View export jobs)
- Risk: read


### Delete an export job

`DELETE /api/v1/exports/{id}`

Removes the job and its artifact.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_create` (Create / delete export jobs)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Job id. |


### Poll one export job

`GET /api/v1/exports/{id}`

The job's current state and progress. Poll this until status reports the job is finished, then download.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_index` (View export jobs)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Job id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such job, or one belonging to another manager's subtree |

#### Note

processed and total drive a progress bar; row_count is the final emitted count and stays 0 until the job finishes. A job that is not yours answers 404 rather than 403, so job ids are not enumerable across resellers.


### Download an export artifact

`GET /api/v1/exports/{id}/download`

Streams the finished file. The ownership check runs again here, because the artifact itself can contain another reseller's card codes and balances.

- Authentication: manager session (JWT) or API token
- Permission: `prm_exports_download` (Download export files)
- Risk: write
- Rate limit bucket: `t_heavy`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Job id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | the job is not yours, or has not produced a file yet |

#### Note

404 until the job has actually produced an artifact, which is indistinguishable from "no such job". Poll the job first rather than treating a download 404 as a permanent failure. This route is on the per-tenant heavy budget.



## Notification Outbox

### Notification Queue

`GET /api/v1/admin/notification-outbox`

- Authentication: manager session (JWT) or API token
- Permission: `prm_log_notifications` (Notification Queue)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-outbox/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-outbox/bulk-retry`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`DELETE /api/v1/admin/notification-outbox/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Notification Queue

`GET /api/v1/admin/notification-outbox/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_log_notifications` (Notification Queue)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-outbox/{id}/retry`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`GET /api/v1/admin/notification-outbox/{id}/status`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Notification Rules

### Manage usage notifications

`GET /api/v1/admin/notification-rules`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`POST /api/v1/admin/notification-rules`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`POST /api/v1/admin/notification-rules/bulk`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write
- Rate limit bucket: `t_egress`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`POST /api/v1/admin/notification-rules/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`GET /api/v1/admin/notification-rules/log`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`DELETE /api/v1/admin/notification-rules/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage usage notifications

`PATCH /api/v1/admin/notification-rules/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_notifications` (Manage usage notifications)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Roles

### List roles

`GET /api/v1/roles`

Every role visible to the tenant, with its permission count and the exact code set it grants. System roles sort first.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 2,
      "tenant_id": 12,
      "name": "support",
      "description": "Read subscribers, reply to tickets",
      "is_system": false,
      "template_key": "support",
      "immutable": false,
      "permission_count": 14,
      "permissions": ["prm_tickets_reply", "prm_tickets_view", "prm_users_index"]
    }
  ]
}
```

#### Note

Un-paginated. template_key is the provisioning slug a seeded role came from, and is null for a hand-made one — it is populated by this list only, not by the role pickers.


### Create a role

`POST /api/v1/roles`

Creates a named permission set. A caller may only grant codes they hold themselves, so a role cannot be used to mint authority its author does not have.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | body | string | yes | Unique within the tenant. Reserved names are refused. |
| `permissions` | body | array | no | Permission codes from the catalogue. Unknown codes are rejected, not dropped. |

#### Request

```json
{
  "name": "front-desk",
  "description": "Sell cards, read subscribers",
  "permissions": ["prm_users_index", "prm_cards_verify", "prm_pos_sell"]
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown permission code, or a reserved role name |
| `ERR_FORBIDDEN` | 403 | the role would grant a permission the caller does not hold |
| `ERR_VALIDATION` | 409 | the role name already exists in this tenant |

#### Note

The containment rule is the point of this endpoint. You cannot author a role carrying a permission you lack, and you cannot assign someone else's role that carries one either — the assign path runs the same check, because otherwise the author check would be trivially bypassed.


### Manage roles & permissions

`POST /api/v1/roles/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete a role

`DELETE /api/v1/roles/{id}`

Removes the role. System and immutable roles are refused, and so is a role that is still assigned.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Role id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_CONFLICT` | 409 | the role is still assigned to a manager |


### Fetch one role

`GET /api/v1/roles/{id}`

The role and the exact set of permission codes it grants.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Role id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_NOT_FOUND` | 404 | no such role in this tenant |


### Update a role

`PATCH /api/v1/roles/{id}`

Edits the name, description and permission set. The immutable administrator role cannot be edited at all.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Role id. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_FORBIDDEN` | 403 | the edit would add a permission the caller does not hold |

#### Note

Changing a role changes the authority of every manager holding it, and every API token those managers own, on the next request. There is no notification and no record against the affected tokens.


### Set a role's subscriber-portal permissions

`PUT /api/v1/roles/{id}/portal-permissions`

The separate set that governs what a SUBSCRIBER may do in the self-service portal, not what a manager may do in the admin API. Different catalogue, different meaning.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Role id. |

#### Note

These are not `prm_*` codes and they do not affect the admin API at all. Confusing the two sets is the usual cause of "I gave the role the permission and nothing changed".



## Branding

### GET /api/v1/branding

`GET /api/v1/branding`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/branding/assets/{key}

`GET /api/v1/branding/assets/{key}`

- Authentication: none
- Rate limit bucket: `branding_asset`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/branding/assets/{slot}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/branding/icons/{key}/{variant}.png

`GET /api/v1/branding/icons/{key}/{variant}.png`

- Authentication: none
- Rate limit bucket: `branding_icon`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/branding/manifest.webmanifest

`GET /api/v1/branding/manifest.webmanifest`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/branding/user/manifest.webmanifest

`GET /api/v1/branding/user/manifest.webmanifest`

- Authentication: none

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Email Templates

### Manage notification channels & templates

`GET /api/v1/admin/email-templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/email-templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/email-templates/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/email-templates/preview`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/email-templates/test`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`DELETE /api/v1/admin/email-templates/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Import

### Import data

`GET /api/v1/admin/import/fields`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import data

`GET /api/v1/admin/import/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import data

`POST /api/v1/admin/import/jobs`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import data

`GET /api/v1/admin/import/jobs/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import data

`POST /api/v1/admin/import/jobs/{id}/cancel`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Import data

`POST /api/v1/admin/import/validate`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_import` (Import data)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Notification Channels

### Manage notification channels & templates

`GET /api/v1/admin/notification-channels`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-channels`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-channels/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`DELETE /api/v1/admin/notification-channels/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`PATCH /api/v1/admin/notification-channels/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-channels/{id}/test`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Trash

### View & restore Trash

`GET /api/v1/admin/trash`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash` (View & restore Trash)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Permanently delete from Trash

`POST /api/v1/admin/trash/bulk-purge`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash_purge` (Permanently delete from Trash)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View & restore Trash

`POST /api/v1/admin/trash/bulk-restore`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash` (View & restore Trash)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Permanently delete from Trash

`POST /api/v1/admin/trash/empty`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash_purge` (Permanently delete from Trash)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View & restore Trash

`GET /api/v1/admin/trash/{id}/preflight`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash` (View & restore Trash)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### View & restore Trash

`POST /api/v1/admin/trash/{id}/restore`

- Authentication: manager session (JWT) or API token
- Permission: `prm_tools_trash` (View & restore Trash)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Groups

### View groups

`GET /api/v1/admin/groups`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_index` (View groups)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Create groups

`POST /api/v1/admin/groups`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_create` (Create groups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete groups

`POST /api/v1/admin/groups/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_delete` (Delete groups)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Delete groups

`DELETE /api/v1/admin/groups/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_delete` (Delete groups)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Edit groups

`PUT /api/v1/admin/groups/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_groups_update` (Edit groups)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Telegram

### Manage notification channels & templates

`POST /api/v1/admin/telegram/broadcast`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_egress`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`GET /api/v1/admin/telegram/broadcast/audience-count`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/telegram/webhook/register`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`GET /api/v1/admin/telegram/webhook/status`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/telegram/webhook/unregister`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Console Sessions

### DELETE /api/v1/admin/console-sessions

`DELETE /api/v1/admin/console-sessions`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_remote`, `prm_nas_devices_remote`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### GET /api/v1/admin/console-sessions

`GET /api/v1/admin/console-sessions`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_remote`, `prm_nas_devices_remote`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### POST /api/v1/admin/console-sessions/bulk-close

`POST /api/v1/admin/console-sessions/bulk-close`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_remote`, `prm_nas_devices_remote`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### DELETE /api/v1/admin/console-sessions/{sid}

`DELETE /api/v1/admin/console-sessions/{sid}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_nas_remote`, `prm_nas_devices_remote`
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Notification Templates

### Manage notification channels & templates

`GET /api/v1/admin/notification-templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-templates`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/notification-templates/bulk-delete`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`DELETE /api/v1/admin/notification-templates/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Pricing

### Manage profile pricing

`GET /api/v1/admin/pricing`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage profile pricing

`GET /api/v1/admin/pricing/manager/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage profile pricing

`PUT /api/v1/admin/pricing/manager/{id}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage profile pricing

`GET /api/v1/admin/pricing/managers`

- Authentication: manager session (JWT) or API token
- Permission: `prm_profiles_pricing` (Manage profile pricing)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Settings

### Manage settings

`GET /api/v1/settings`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`PATCH /api/v1/settings`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/settings/reset`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`GET /api/v1/settings/{category}/{key}`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Setup

### Manage settings

`GET /api/v1/admin/setup/checklist`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`DELETE /api/v1/admin/setup/sample`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`POST /api/v1/admin/setup/sample`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_heavy`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage settings

`PATCH /api/v1/admin/setup/state`

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Telegram Manager

### Use the manager Telegram bot

`POST /api/v1/admin/telegram-manager/link`

- Authentication: manager session (JWT) or API token
- Permission: `prm_telegram_console` (Use the manager Telegram bot)
- Risk: write
- Rate limit bucket: `t_mutate`
- Not available to API tokens: this route requires an interactive manager session

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/telegram-manager/webhook/register`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`GET /api/v1/admin/telegram-manager/webhook/status`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Manage notification channels & templates

`POST /api/v1/admin/telegram-manager/webhook/unregister`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Billing

### List invoices across subscribers

`GET /api/v1/billing/invoices`

Every invoice the caller may see, in one list, with filters for reconciling a period. A caller without tenant-wide visibility sees only invoices belonging to subscribers in their own manager subtree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_billing` (Billing & invoices)
- Risk: write

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[status]` | query | string | no | Payment status. |
| `filter[username]` | query | string | no | Narrow to one subscriber by username. |
| `filter[date_from]` | query | string | no | Inclusive lower bound. A malformed value is a 400, not an ignored filter. |
| `filter[date_to]` | query | string | no | Inclusive upper bound. |
| `filter[amount_min]` | query | number | no | Inclusive lower amount bound. |
| `filter[amount_max]` | query | number | no | Inclusive upper amount bound. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 51204,
      "user_id": 4711,
      "username": "ahmed",
      "invoice_number": "INV-2026-000512",
      "type": "activation",
      "amount": 171.00,
      "discount": 0.00,
      "vat": 14.00,
      "status": "paid",
      "description": "Home 20M (activate)",
      "payment_method": "manager_balance",
      "due_date": "2026-09-20 00:00:00",
      "paid_on": "2026-09-20 09:15:02",
      "created_by_manager_id": 41,
      "created_by_name": "cairo-reseller",
      "created_at": "2026-09-20 09:15:02"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1284, "has_next": true }
}
```

#### Note

username is populated only on this cross-subscriber list, which joins the subscriber table. The per-subscriber list and the single-invoice fetch leave it empty, because there the subscriber is already known.


### Issue an invoice

`POST /api/v1/billing/invoices`

Creates an invoice against a named subscriber from line items. discount and vat are percentages from 0 to 100, and the total is computed from the items — never taken from the request.

- Authentication: manager session (JWT) or API token
- Permission: `prm_billing` (Billing & invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `user_id` | body | integer | yes | The subscriber being invoiced. |
| `items` | body | array | yes | At least one line, each with name, qty, unit_price and an optional per-line tax. |
| `discount` | body | number | no | Percentage from 0 to 100, not an amount. |
| `vat` | body | number | no | Percentage from 0 to 100, not an amount. |
| `due_date` | body | string | no | yyyy-MM-dd HH:mm:ss in UTC. |
| `mark_paid` | body | boolean | no | Record the new invoice as already settled. |

#### Request

```json
{
  "user_id": 4711,
  "description": "September installation",
  "discount": 0,
  "vat": 14,
  "due_date": "2026-10-01 00:00:00",
  "items": [
    { "name": "Router CPE", "qty": 1, "unit_price": 900.00, "tax": 0 },
    { "name": "Installation", "qty": 1, "unit_price": 250.00, "tax": 0 }
  ]
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | user_id missing, no items, an unnamed item, or a discount or VAT outside 0 to 100 |
| `ERR_NOT_FOUND` | 404 | the subscriber does not exist or is outside the caller's subtree |

#### Note

discount and vat are PERCENTAGES, and the validator rejects anything above 100. Sending 171.00 in the vat field to mean "171 in tax" is a 400, not a silently large invoice.


### Billing & invoices

`POST /api/v1/billing/invoices/bulk-pay`

- Authentication: manager session (JWT) or API token
- Permission: `prm_billing` (Billing & invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Logs

### User Auth Log

`GET /api/v1/admin/logs/auth`

- Authentication: manager session (JWT) or API token
- Permission: `prm_log_auth` (User Auth Log)
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### System Log (manager activity)

`GET /api/v1/admin/logs/system`

- Authentication: manager session (JWT) or API token
- Permission: `prm_log_system` (System Log (manager activity))
- Risk: read

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## License

### GET /api/v1/license

`GET /api/v1/license`

- Authentication: manager session (JWT) or API token

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Notification Event Options

### Manage notification channels & templates

`PUT /api/v1/admin/notification-event-options`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Notification Events

### Manage notification channels & templates

`GET /api/v1/admin/notification-events`

- Authentication: manager session (JWT) or API token
- Permission: `prm_notifications_manage` (Manage notification channels & templates)
- Risk: write

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Permissions

### List the permission catalogue

`GET /api/v1/permissions`

Every permission code this build defines, with its group, label, help text, stated effect and risk class. This is the authoritative list a role editor or a token scope picker should render from.

- Authentication: manager session (JWT) or API token
- Permission: `prm_roles_manage` (Manage roles & permissions)
- Risk: danger

#### Response — 200 OK

```json
{
  "data": [
    {
      "code": "prm_users_index",
      "group": "Subscribers",
      "label": "View subscribers",
      "desc": "See the subscriber list and open a subscriber record.",
      "effect": "Read-only.",
      "risk": "read"
    }
  ]
}
```

#### Note

English only, and deliberately not translated — these are operator-facing catalogue strings baked into the build, not localized messages. risk is read, write or danger, and is the right signal for warning someone before they tick a box.



## Postpaid

### Billing & invoices

`POST /api/v1/admin/postpaid/generate-now`

- Authentication: manager session (JWT) or API token
- Permission: `prm_billing` (Billing & invoices)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## System

### GET /api/v1/system/updates

`GET /api/v1/system/updates`

- Authentication: manager session (JWT) or API token

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._



## Tenants

### POST /api/v1/tenants

`POST /api/v1/tenants`

- Authentication: instance shared secret header

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._