API reference · Hamroh IO

01Conventions#

Requests use JSON; firmware uploads use multipart/form-data. The global ValidationPipe rejects fields outside the DTO and applies declared transforms. Responses do not share a universal success wrapper.

Read-only health request

curl --fail --silent https://api.hamrohio.uz/health

Health response shape

{
  "status": "ok",
  "checks": { "api": true, "database": true, "objectStorage": true },
  "timestamp": "2026-09-10T00:00:00.000Z"
}

02Authentication#

Flow	Credential	Usage
Admin	hamroh_admin cookie	12-hour session after login. Roles are enforced per route.
Pairing	Authorization: Bearer <credential>	For paired installation /devices/me and revoke. Refresh accepts the credential in its body.
Device proof	x-hamroh-timestamp + x-hamroh-proof	Heartbeat, firmware latest, report and current installation. Both headers are required together.
Public	Unauthenticated, rate limited	Health and preorder flow. Pairing challenge/claim verifies dedicated proof before issuing a credential.

The device timestamp is Unix milliseconds within ±5 minutes of server time. The proof is a hex HMAC-SHA256; the Desktop obtains it from the device. Do not copy the device secret into a browser or integration script.

Operation	Proof payload
heartbeat	timestamp.serial.firmwareVersion.uptime
firmware/latest	timestamp.serial.currentFirmware
installations/current	timestamp.serial.installation-status.installationId-or-latest
firmware/report	timestamp.serial.releaseId.installationId.status

The legacy report contract without installationId uses timestamp.serial.releaseId.status. The timestamp window enforces freshness, not a one-time nonce for every request.

03Key integration flows#

Pairing: challenge → hardware proof → claim → credential. Challenges expire after five minutes.
Firmware: package inspect → Admin notes and channel/target → DRAFT → READY → ROLLING_OUT. READY is not an automatic rollout.
Preorder: public config → create with idempotency-key. The same request and key should not create a duplicate.

04Errors & limits#

Error response shape

{
  "error": {
    "code": "ADMIN_AUTH_REQUIRED",
    "message": "Admin authentication is required.",
    "requestId": "example-request-id"
  }
}

Status	Meaning	Client action
400	DTO or business-rule rejection	Correct the request
401 / 403	Credential or role rejected	Check session/proof and authorization
409	Duplicate or lifecycle conflict	Read the current state
429	Rate limit	Back off; do not retry indefinitely
5xx	Service failure	Retain requestId and check service state

The default throttler is configured for 120 requests per 60 seconds. Overrides include login 5/min, pairing challenge 10/min, claim 5/min, package inspect 10/min and package create 5/min. The current configuration does not demonstrate shared distributed rate-limit storage.

05Endpoint catalog#

The catalog includes methods, paths, access roles and DTO fields. Response schemas are included only where separately reviewed against code; full response shapes are not invented for other operations.

80 endpoints

GET/v1/admin/teamadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:12

POST/v1/admin/teamadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`name`	`string`Required	minLength: 2; maxLength: 120
`email`	`string`Required	format: email; minLength: 3; maxLength: 160
`role`	`string`Required	SUPER_ADMIN · ADMIN · OPERATIONS · SALES · SUPPORT · FIRMWARE_MANAGER · VIEWER

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:20

GET/v1/admin/team/optionsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:16

PATCH/v1/admin/team/{id}/roleadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`role`	`string`Required	SUPER_ADMIN · ADMIN · OPERATIONS · SALES · SUPPORT · FIRMWARE_MANAGER · VIEWER

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:24

PATCH/v1/admin/team/{id}/statusadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`status`	`string`Required	ACTIVE · SUSPENDED · DISABLED

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:30

POST/v1/admin/team/{id}/reset-passwordadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:36

POST/v1/admin/team/{id}/revoke-sessionsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/admin-users/admin-users.controller.ts:42

GET/v1/admin/analytics/salesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`range`	query	stringtoday · 7d · 30d · 90d · year · custom; default: 30d	—
`from`	query	string	—
`to`	query	string	—
`currency`	query	stringdefault: UZS	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/analytics/analytics.controller.ts:12

GET/v1/admin/analytics/operationsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/analytics/analytics.controller.ts:13

GET/v1/admin/auditadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`skip`	query	string	—
`take`	query	string	—
`action`	query	string	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/audit/audit.controller.ts:11

POST/v1/admin/auth/loginPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 5 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`email`	`string`Required	format: email
`password`	`string`Required	format: password; minLength: 8

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:12

POST/v1/admin/auth/logoutPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 120 / 60s

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:19

GET/v1/admin/auth/meadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: —
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:26

PUT/v1/admin/auth/passwordadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: —
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`currentPassword`	`string`Required	format: password; minLength: 8; maxLength: 128
`newPassword`	`string`Required	format: password; minLength: 12; maxLength: 128; pattern: ^(?=.[a-z])(?=.[A-Z])(?=.\d)(?=.[^A-Za-z0-9]).+$

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:32

GET/v1/admin/auth/sessionsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: —
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:37

DELETE/v1/admin/auth/sessions/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: —
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/auth/auth.controller.ts:40

GET/v1/admin/customersadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	string	—
`preorderStatus`	query	stringNEW · CONTACTED · CONFIRMED · PAYMENT_PENDING · DEPOSIT_PAID · READY_TO_SHIP · FULFILLED · CANCELLED	—
`source`	query	string	—
`language`	query	stringuz · en · ru	—
`assignedAdminId`	query	string	—
`dateFrom`	query	stringformat: date-time	—
`dateTo`	query	stringformat: date-time	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 100; default: 25	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/customers/customers.controller.ts:12

POST/v1/admin/customersadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`fullName`	`string`Required	minLength: 2; maxLength: 120
`email`	`string`Optional	format: email
`phone`	`string`Optional	minLength: 5; maxLength: 32
`company`	`string`Optional	minLength: 2; maxLength: 120
`country`	`string`Optional	minLength: 2; maxLength: 80
`city`	`string`Optional	minLength: 2; maxLength: 80
`region`	`string`Optional	minLength: 2; maxLength: 80
`telegramUsername`	`string`Optional	minLength: 5; maxLength: 32
`preferredLanguage`	`string`Optional	uz · en · ru
`notes`	`string`Optional	minLength: 0; maxLength: 1000

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/customers/customers.controller.ts:23

GET/v1/admin/customers/export.csvadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	string	—
`preorderStatus`	query	stringNEW · CONTACTED · CONFIRMED · PAYMENT_PENDING · DEPOSIT_PAID · READY_TO_SHIP · FULFILLED · CANCELLED	—
`source`	query	string	—
`language`	query	stringuz · en · ru	—
`assignedAdminId`	query	string	—
`dateFrom`	query	stringformat: date-time	—
`dateTo`	query	stringformat: date-time	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 100; default: 25	—

Response

HTTP 200 · text/csv

apps/api/src/customers/customers.controller.ts:14

GET/v1/admin/customers/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/customers/customers.controller.ts:21

PATCH/v1/admin/customers/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`fullName`	`string`Optional	minLength: 2; maxLength: 120
`email`	`string`Optional	format: email
`phone`	`string`Optional	minLength: 5; maxLength: 32
`company`	`string`Optional	minLength: 2; maxLength: 120
`country`	`string`Optional	minLength: 2; maxLength: 80
`city`	`string`Optional	minLength: 2; maxLength: 80
`region`	`string`Optional	minLength: 2; maxLength: 80
`telegramUsername`	`string`Optional	minLength: 5; maxLength: 32
`preferredLanguage`	`string`Optional	uz · en · ru
`notes`	`string`Optional	minLength: 0; maxLength: 1000

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/customers/customers.controller.ts:25

GET/v1/admin/devicesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	string	—
`status`	query	stringINVENTORY · READY · SOLD · CLAIMED · ACTIVE · RETURNED · SUSPENDED · REVOKED · REPAIR · RETIRED	—
`hardwareRevision`	query	string	—
`firmware`	query	string	—
`batch`	query	string	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 100; default: 50	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:12

GET/v1/admin/devices/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:15

GET/v1/admin/claim-codesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`skip`	query	string	—
`take`	query	string	—
`status`	query	string	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:18

POST/v1/admin/devices/batchesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`batchCode`	`string`Required	minLength: 3; maxLength: 64
`model`	`string`Required	minLength: 2; maxLength: 32
`hardwareRevision`	`string`Required	minLength: 1; maxLength: 64
`quantity`	`integer`Required	minimum: 1; maximum: 500
`expiresAt`	`string`Optional	—

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:23

GET/v1/admin/inventory/batchesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	string	—
`status`	query	stringDRAFT · READY · PROVISIONING · COMPLETED · ARCHIVED · CANCELLED	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 100; default: 50	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:26

POST/v1/admin/inventory/batchesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`code`	`string`Required	minLength: 3; maxLength: 64
`model`	`string`Required	minLength: 2; maxLength: 32
`hardwareRevision`	`string`Required	minLength: 1; maxLength: 64
`quantity`	`integer`Required	minimum: 1; maximum: 500
`notes`	`string`Optional	minLength: 0; maxLength: 1000
`source`	`string`Optional	minLength: 1; maxLength: 64

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:29

GET/v1/admin/inventory/batches/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:32

PATCH/v1/admin/inventory/batches/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`code`	`string`Optional	minLength: 3; maxLength: 64
`model`	`string`Optional	minLength: 2; maxLength: 32
`hardwareRevision`	`string`Optional	minLength: 1; maxLength: 64
`quantity`	`integer`Optional	minimum: 1; maximum: 500
`notes`	`string`Optional	minLength: 0; maxLength: 1000
`source`	`string`Optional	minLength: 1; maxLength: 64
`status`	`string`Optional	DRAFT · READY · PROVISIONING · COMPLETED · ARCHIVED · CANCELLED

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:35

DELETE/v1/admin/inventory/batches/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN
Rate limit: 10 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:44

POST/v1/admin/inventory/batches/{id}/provisionadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS
Rate limit: 10 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`expiresAt`	`string`Optional	—

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:38

POST/v1/admin/inventory/batches/{id}/archiveadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:41

PATCH/v1/admin/devices/{id}/statusadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SUPPORT
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`status`	`string`Required	INVENTORY · READY · SOLD · CLAIMED · ACTIVE · RETURNED · SUSPENDED · REVOKED · REPAIR · RETIRED
`reason`	`string`Required	minLength: 3

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:47

POST/v1/admin/devices/{id}/claim/resetadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SUPPORT
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`reason`	`string`Required	minLength: 3
`expiresAt`	`string`Optional	—

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:50

POST/v1/admin/devices/{id}/transferadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SUPPORT
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`customerEmail`	`string`Required	format: email
`customerName`	`string`Optional	—
`reason`	`string`Required	minLength: 3

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:53

POST/v1/admin/devices/{id}/provisioning-envelopeadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, OPERATIONS
Rate limit: 3 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`serialNumber`	`string`Required	minLength: 16; maxLength: 40
`expectedHardwareRevision`	`string`Required	minLength: 1; maxLength: 64
`provisionerPublicKey`	`string`Required	minLength: 256; maxLength: 8192

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:56

POST/v1/devices/heartbeatdeviceProof + deviceTimestamp

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: deviceProof + deviceTimestamp
Roles: —
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`serial`	`string`Required	—
`firmwareVersion`	`string`Required	—
`firmwareBuildNumber`	`integer`Optional	minimum: 0
`hardwareRevision`	`string`Optional	minLength: 1; maxLength: 64
`otaSlot`	`string`Optional	ota_0 · ota_1
`appVersion`	`string`Required	—
`uptime`	`integer`Required	minimum: 0
`wifiRSSI`	`integer`Optional	minimum: -120; maximum: 0
`freeHeap`	`integer`Optional	minimum: 0
`temperature`	`number`Optional	minimum: -40; maximum: 125
`status`	`string`Optional	default: healthy

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/devices/devices.controller.ts:61

GET/v1/admin/firmwareadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:15

POST/v1/admin/firmwareLegacyadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation. Legacy binary upload. Prefer the signed package route.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Request `multipart/form-data`

Field	Type / requirement	Constraints
`version`	`string`Required	pattern: ^\d{1,4}\.\d{1,4}\.\d{1,4}$
`buildNumber`	`integer`Required	minimum: 1; maximum: 2147483647
`hardwareRevision`	`string`Required	pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$
`channel`	`string`Required	INTERNAL · BETA · STABLE
`securityVersion`	`integer`Optional	minimum: 0; default: 0
`releaseNotes`	`string[]`Required	—
`mandatory`	`boolean`Optional	default: false
`mandatoryAfter`	`string`Optional	format: date-time
`rolloutPercentage`	`integer`Optional	minimum: 0; maximum: 100; default: 0
`signature`	`string`Optional	—
`targetDeviceId`	`string`Optional	—
`file`	`file`Required	format: binary

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:32

GET/v1/admin/firmware/package-devicesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`hardwareRevision`	query	stringmaxLength: 64	Yes
`search`	query	stringmaxLength: 64	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:18

POST/v1/admin/firmware/packages/inspectadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER
Rate limit: 10 / 60s

Request `multipart/form-data`

Field	Type / requirement	Constraints
`file`	`file`Required	format: binary

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:21

POST/v1/admin/firmware/packagesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation. Signed .hrelease only; administrator-authored releaseNotes required. INTERNAL requires a compatible targetDeviceId. Creates DRAFT only.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER
Rate limit: 5 / 60s

Request `multipart/form-data`

Field	Type / requirement	Constraints
`channel`	`string`Required	INTERNAL · BETA · STABLE
`targetDeviceId`	`string`Optional	minLength: 1; maxLength: 64
`mandatory`	`boolean`Optional	default: false
`releaseNotes`	`string`Required	minLength: 1; maxLength: 8000
`file`	`file`Required	format: binary

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:25

GET/v1/admin/firmware/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:29

PATCH/v1/admin/firmware/{id}/lifecycleadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, FIRMWARE_MANAGER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`status`	`string`Required	DRAFT · READY · ROLLING_OUT · PAUSED · COMPLETED · REVOKED
`rolloutPercentage`	`integer`Optional	minimum: 0; maximum: 100

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:35

POST/v1/admin/firmware/{id}/maintenance-grantadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, FIRMWARE_MANAGER
Rate limit: 3 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`expectedMac`	`string`Required	pattern: ^[0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}$
`targetSerial`	`string`Required	minLength: 1
`expectedVersion`	`string`Required	minLength: 1
`expectedBuild`	`integer`Required	minimum: 1
`expectedHardwareRevision`	`string`Required	minLength: 1
`maintenancePurpose`	`string`Required	ONE_TIME_IDENTITY_PROVISIONING

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:38

POST/v1/admin/firmware/installations/{installationId}/reconcileadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, FIRMWARE_MANAGER
Rate limit: 3 / 60s

Parameters

Name	In	Type	Required
`installationId`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`releaseId`	`string`Required	minLength: 1
`serial`	`string`Required	minLength: 1
`expectedVersion`	`string`Required	minLength: 1
`expectedBuild`	`integer`Required	minimum: 1
`expectedSlot`	`string`Required	ota_0 · ota_1
`observedBootState`	`string`Required	valid
`observedOtaSessionState`	`string`Required	IDLE
`reason`	`string`Required	POST_BOOT_FALSE_NEGATIVE_RECONCILIATION

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:43

GET/v1/firmware/latestdeviceProof + deviceTimestamp

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation. IMPORTANT: eligibility lookup can create an AVAILABLE installation record; this GET is not side-effect-free.

Auth: deviceProof + deviceTimestamp
Roles: —
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`serial`	query	string	Yes
`hardwareRevision`	query	string	Yes
`currentFirmware`	query	string	Yes
`appVersion`	query	string	Yes
`channel`	query	stringINTERNAL · BETA · STABLE; default: STABLE	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:48

POST/v1/admin/firmware/installations/{installationId}/interruptionadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, FIRMWARE_MANAGER
Rate limit: 3 / 60s

Parameters

Name	In	Type	Required
`installationId`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`releaseId`	`string`Required	minLength: 1; maxLength: 64
`serial`	`string`Required	minLength: 1; maxLength: 64
`expectedVersion`	`string`Required	minLength: 1; maxLength: 32
`expectedBuild`	`integer`Required	minimum: 1
`expectedFailureReason`	`string`Required	minLength: 1; maxLength: 256
`failureCode`	`string`Required	USER_CANCELLED_BY_OPERATOR

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:51

GET/v1/firmware/installations/currentdeviceProof + deviceTimestamp

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation. Read-only recovery lookup: does not create an installation or sign a download URL.

Auth: deviceProof + deviceTimestamp
Roles: —
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`serial`	query	stringminLength: 1; maxLength: 64	Yes
`installationId`	query	stringminLength: 1; maxLength: 64	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:57

POST/v1/firmware/reportdeviceProof + deviceTimestamp

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: deviceProof + deviceTimestamp
Roles: —
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`serial`	`string`Required	—
`releaseId`	`string`Required	—
`installationId`	`string`Optional	—
`status`	`string`Required	AVAILABLE · QUEUED · DOWNLOADING · VERIFYING · TRANSFERRING · INSTALLING · REBOOTING · VALIDATING · SUCCESS · FAILED · ROLLED_BACK
`fromVersion`	`string`Optional	—
`failureReason`	`string`Optional	—

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/firmware/firmware.controller.ts:62

GET/healthPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 120 / 60s

Response

HTTP 200 · application/json

Field	Type / requirement	Constraints
`status`	`string`Required	ok · degraded
`checks`	`object`Required	—
`timestamp`	`string`Required	format: date-time

apps/api/src/health/health.controller.ts:9

POST/v1/devices/pair/challengePublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 10 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`serial`	`string`Required	minLength: 8
`installationId`	`string`Required	minLength: 16; maxLength: 128

Response

HTTP 201 · application/json

Field	Type / requirement	Constraints
`challengeId`	`string`Optional	—
`serial`	`string`Optional	—
`nonce`	`string`Optional	—
`expiresAt`	`string`Optional	format: date-time
`proofPayload`	`string`Optional	—

apps/api/src/pairing/pairing.controller.ts:10

POST/v1/devices/pair/claimPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 5 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`serial`	`string`Required	minLength: 8
`installationId`	`string`Required	minLength: 16; maxLength: 128
`challengeId`	`string`Required	minLength: 16
`nonce`	`string`Required	minLength: 24
`claimCode`	`string`Required	minLength: 16
`hardwareProof`	`string`Required	minLength: 32
`publicKey`	`string`Required	minLength: 8
`deviceName`	`string`Required	minLength: 1; maxLength: 128
`appVersion`	`string`Required	minLength: 1; maxLength: 32
`customerEmail`	`string`Optional	format: email
`customerName`	`string`Optional	—

Response

HTTP 201 · application/json

Field	Type / requirement	Constraints
`credential`	`string`Optional	—
`expiresAt`	`string`Optional	format: date-time
`device`	`object`Optional	—
`offlineCapable`	`boolean`Optional	—

apps/api/src/pairing/pairing.controller.ts:13

POST/v1/devices/pair/code-statusPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 8 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`claimCode`	`string`Required	minLength: 16

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/pairing/pairing.controller.ts:16

POST/v1/devices/pair/refreshPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`credential`	`string`Required	minLength: 16

Response

HTTP 201 · application/json

Field	Type / requirement	Constraints
`credential`	`string`Optional	—
`expiresAt`	`string`Optional	format: date-time
`device`	`object`Optional	—
`offlineCapable`	`boolean`Optional	—

apps/api/src/pairing/pairing.controller.ts:20

POST/v1/devices/pair/revokepairingBearer

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: pairingBearer
Roles: —
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`installationId`	`string`Required	minLength: 16; maxLength: 128

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/pairing/pairing.controller.ts:23

GET/v1/devices/mepairingBearer

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: pairingBearer
Roles: —
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/pairing/pairing.controller.ts:26

GET/v1/public/preorder-configPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 60 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:36

POST/v1/public/preordersPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 5 / 60s

Parameters

Name	In	Type	Required
`idempotency-key`	header	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`fullName`	`string`Required	minLength: 2; maxLength: 120
`phone`	`string`Required	minLength: 8; maxLength: 32
`region`	`string`Required	minLength: 2; maxLength: 80
`productColor`	`string`Optional	BLACK · WHITE · LAVENDER
`paymentMethod`	`string`Optional	DEPOSIT · FULL
`note`	`string`Optional	minLength: 1; maxLength: 500
`city`	`string`Optional	minLength: 2; maxLength: 80
`email`	`string`Optional	format: email; minLength: 3; maxLength: 160
`telegramUsername`	`string`Optional	pattern: ^@?[A-Za-z0-9_]{5,32}$
`quantity`	`integer`Optional	minimum: 1; maximum: 20; default: 1
`locale`	`string`Required	uz · en · ru
`website`	`string`Optional	minLength: 0; maxLength: 0
`utmSource`	`string`Optional	minLength: 1; maxLength: 120
`utmMedium`	`string`Optional	minLength: 1; maxLength: 120
`utmCampaign`	`string`Optional	minLength: 1; maxLength: 160
`utmContent`	`string`Optional	minLength: 1; maxLength: 160
`utmTerm`	`string`Optional	minLength: 1; maxLength: 160
`referrer`	`string`Optional	format: uri; minLength: 1; maxLength: 500

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:40

POST/v1/public/preorder-events/viewPublic

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: Public
Roles: —
Rate limit: 20 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`anonymousSessionId`	`string`Required	pattern: ^[A-Za-z0-9_-]{16,96}$
`locale`	`string`Required	uz · en · ru
`utmSource`	`string`Optional	minLength: 1; maxLength: 120
`utmMedium`	`string`Optional	minLength: 1; maxLength: 120
`utmCampaign`	`string`Optional	minLength: 1; maxLength: 160
`utmContent`	`string`Optional	minLength: 1; maxLength: 160
`utmTerm`	`string`Optional	minLength: 1; maxLength: 160
`referrer`	`string`Optional	format: uri; minLength: 1; maxLength: 500

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:50

GET/v1/admin/preordersadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	stringminLength: 1; maxLength: 160	—
`status`	query	stringNEW · CONTACTED · CONFIRMED · PAYMENT_PENDING · DEPOSIT_PAID · READY_TO_SHIP · FULFILLED · CANCELLED	—
`source`	query	stringminLength: 1; maxLength: 80	—
`locale`	query	stringuz · en · ru	—
`assignedAdminId`	query	string	—
`dateFrom`	query	stringformat: date-time	—
`dateTo`	query	stringformat: date-time	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 200; default: 50	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:60

GET/v1/admin/preorders/analyticsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:64

GET/v1/admin/preorders/export.csvadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	stringminLength: 1; maxLength: 160	—
`status`	query	stringNEW · CONTACTED · CONFIRMED · PAYMENT_PENDING · DEPOSIT_PAID · READY_TO_SHIP · FULFILLED · CANCELLED	—
`source`	query	stringminLength: 1; maxLength: 80	—
`locale`	query	stringuz · en · ru	—
`assignedAdminId`	query	string	—
`dateFrom`	query	stringformat: date-time	—
`dateTo`	query	stringformat: date-time	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 200; default: 50	—

Response

HTTP 200 · text/csv

apps/api/src/preorders/preorders.controller.ts:68

GET/v1/admin/preorders/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:77

DELETE/v1/admin/preorders/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`preorderNumber`	`string`Required	minLength: 8; maxLength: 40
`reason`	`string`Required	minLength: 4; maxLength: 240

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:81

PATCH/v1/admin/preorders/{id}/statusadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`status`	`string`Required	NEW · CONTACTED · CONFIRMED · PAYMENT_PENDING · DEPOSIT_PAID · READY_TO_SHIP · FULFILLED · CANCELLED
`note`	`string`Optional	minLength: 2; maxLength: 500

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:87

PATCH/v1/admin/preorders/{id}/assignmentadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`adminId`	`string`Optional	minLength: 1; maxLength: 80; Conditional validation: inspect the operation policy.

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:93

POST/v1/admin/preorders/customers/{customerId}/notesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`customerId`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`content`	`string`Required	minLength: 2; maxLength: 2000

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:99

GET/v1/admin/preorder-settingsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:115

PUT/v1/admin/preorder-settingsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`preOrderEnabled`	`boolean`Required	—
`productName`	`string`Required	minLength: 2; maxLength: 120
`currency`	`string`Required	pattern: ^[A-Z]{3}$
`fullPrice`	`integer`Optional	minimum: 0; maximum: 2000000000
`depositAmount`	`integer`Optional	minimum: 0; maximum: 2000000000
`expectedDeliveryTextUz`	`string`Required	minLength: 2; maxLength: 240
`expectedDeliveryTextEn`	`string`Required	minLength: 2; maxLength: 240
`expectedDeliveryTextRu`	`string`Required	minLength: 2; maxLength: 240
`maxQuantityPerOrder`	`integer`Required	minimum: 1; maximum: 20
`preorderCapacity`	`integer`Optional	minimum: 1; maximum: 1000000
`contactPhone`	`string`Optional	minLength: 5; maxLength: 32
`supportTelegram`	`string`Optional	format: uri; minLength: 8; maxLength: 300
`allowManualDepositConfirmation`	`boolean`Required	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/preorders/preorders.controller.ts:119

GET/v1/admin/salesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`search`	query	string	—
`status`	query	stringDRAFT · PENDING · PAID · FULFILLED · CANCELLED · REFUNDED	—
`paymentStatus`	query	stringUNPAID · PARTIAL · PAID · REFUNDED	—
`channel`	query	stringDIRECT · INSTAGRAM · TELEGRAM · WEBSITE · RESELLER · OFFLINE · OTHER	—
`from`	query	string	—
`to`	query	string	—
`skip`	query	integerminimum: 0; default: 0	—
`take`	query	integerminimum: 1; maximum: 100; default: 25	—

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:12

POST/v1/admin/salesadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`customer`	`SaleCustomerDto`Required	—
`deviceId`	`string`Required	—
`unitPrice`	`integer`Required	minimum: 0; maximum: 2000000000
`discount`	`integer`Optional	minimum: 0; maximum: 2000000000; default: 0
`currency`	`string`Optional	minLength: 3; maxLength: 3; default: UZS
`paymentStatus`	`string`Required	UNPAID · PARTIAL · PAID · REFUNDED
`salesChannel`	`string`Required	DIRECT · INSTAGRAM · TELEGRAM · WEBSITE · RESELLER · OFFLINE · OTHER
`soldAt`	`string`Optional	format: date-time
`notes`	`string`Optional	minLength: 0; maxLength: 1000

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:16

GET/v1/admin/sales/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES, SUPPORT, VIEWER
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:14

PATCH/v1/admin/sales/{id}adminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 120 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`customerId`	`string`Optional	—
`paymentStatus`	`string`Optional	UNPAID · PARTIAL · PAID · REFUNDED
`salesChannel`	`string`Optional	DIRECT · INSTAGRAM · TELEGRAM · WEBSITE · RESELLER · OFFLINE · OTHER
`notes`	`string`Optional	minLength: 0; maxLength: 1000
`unitPrice`	`integer`Optional	minimum: 0; maximum: 2000000000
`discount`	`integer`Optional	minimum: 0; maximum: 2000000000

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:18

POST/v1/admin/sales/{id}/canceladminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 20 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`reason`	`string`Required	minLength: 3

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:20

POST/v1/admin/sales/{id}/refundadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, SALES
Rate limit: 20 / 60s

Parameters

Name	In	Type	Required
`id`	path	string	Yes

Request `application/json`

Field	Type / requirement	Constraints
`reason`	`string`Required	minLength: 3
`amount`	`integer`Required	minimum: 1; maximum: 2000000000
`deviceDisposition`	`string`Optional	RETURNED · REVOKED

Response

HTTP 201 · An exhaustive response schema is not published in this snapshot.

apps/api/src/sales/sales.controller.ts:22

GET/v1/admin/overviewadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, OPERATIONS, SALES, SUPPORT, FIRMWARE_MANAGER, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/settings/settings.controller.ts:12

GET/v1/admin/settingsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN, VIEWER
Rate limit: 120 / 60s

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/settings/settings.controller.ts:15

PUT/v1/admin/settingsadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`maximumMacsPerDevice`	`integer`Required	minimum: 1; maximum: 10
`heartbeatTimeoutSeconds`	`integer`Required	minimum: 60; maximum: 86400
`pairingCertificateDays`	`integer`Required	minimum: 7; maximum: 730
`defaultFirmwareChannel`	`string`Required	INTERNAL · BETA · STABLE
`defaultRolloutPercentage`	`integer`Required	minimum: 0; maximum: 100

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/settings/settings.controller.ts:18

PUT/v1/admin/settings/businessadminCookie

Access policy

Request schema and access metadata extracted from controller and DTO source. Business rules may impose additional constraints. No live requests are sent by this documentation.

Auth: adminCookie
Roles: SUPER_ADMIN, ADMIN
Rate limit: 120 / 60s

Request `application/json`

Field	Type / requirement	Constraints
`onlineThresholdMinutes`	`integer`Required	minimum: 1; maximum: 1440
`activeThresholdDays`	`integer`Required	minimum: 1; maximum: 365
`companyName`	`string`Required	minLength: 2; maxLength: 120
`defaultCurrency`	`string`Required	minLength: 3; maxLength: 3
`defaultDevicePrice`	`integer`Required	minimum: 0; maximum: 2000000000
`orderNumberPrefix`	`string`Required	minLength: 2; maxLength: 12

Response

HTTP 200 · An exhaustive response schema is not published in this snapshot.

apps/api/src/settings/settings.controller.ts:21

01Conventions#

02Authentication#

03Key integration flows#

04Errors & limits#

05Endpoint catalog#

Access policy

Response

Access policy

Request application/json

Response

Access policy

Response

Access policy

Parameters

Request application/json

Response

Access policy

Parameters

Request application/json

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Response

Access policy

Parameters

Response

Access policy

Request application/json

Response

Access policy

Response

Access policy

Response

Access policy

Request application/json

Response

Access policy

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Request application/json

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Parameters

Request application/json

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Parameters

Response

Access policy

Request application/json

Response

Access policy

Parameters

Response

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `application/json`

Request `multipart/form-data`

Request `multipart/form-data`

Request `multipart/form-data`

Request `application/json`

Request `application/json`

Request `application/json`