XUS Firmware API v1

Programmatic access to the firmware catalog and downloads. Access is granted per account and shares the daily limit and validity window of that account's XUS API subscription. The daily counter resets at 00:00 UTC.

1. Authentication

Every request carries your API key in a header — either form works:

Authorization: Bearer mbxus_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978
X-API-Key: mbxus_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978

The key is shown once when it is created. Store it securely; it cannot be recovered.
One active key per account. Generating a new key immediately revokes the previous one.
A key may be locked to a list of allowed IP addresses. Requests from any other address get 403 ip_not_allowed.
HTTPS only. Send Content-Type: application/json on every request, including the GET ones that carry no body.

2. Base URL & endpoints

https://mbcare.ru/api/v1/xus/{endpoint}

Endpoint	Method	Purpose	Metered
`/list`	GET / POST	Firmware catalog (names) + total for change detection	no
`/download`	GET / POST	Resolve a firmware name to a time-limited download URL	yes — see §5

3. Response headers

Header	Meaning
`X-Request-Id`	Unique id for the request, on every response — quote it in support tickets. It is also repeated in the body of error responses as `requestId`.
`Retry-After`	On `429` — seconds to wait before retrying.

4. GET /list

GEThttps://mbcare.ru/api/v1/xus/list

Returns firmware names as a flat array of strings, plus total — compare total to your last sync to tell whether the catalog changed without diffing the list. With no limit the whole catalog comes back in one response; use cursor to page.

Field	Required	Description
`q`	no	Substring filter on the name (≤ 255 chars).
`cursor`	no	Last `name` from the previous page (exclusive). Keep calling with the previous `nextCursor` while `hasMore` is true.
`limit`	no	Max rows to return. Omit for the full catalog.

curl -s "https://mbcare.ru/api/v1/xus/list?q=2239020042&limit=10" \
  -H "Authorization: Bearer $MBXUS_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "total": 2,
  "count": 2,
  "hasMore": false,
  "nextCursor": null,
  "items": [ "2239020042_001-SMR-20260708_1212.zip", "2239020042_262509.bin" ]
}

5. GET /download

GEThttps://mbcare.ru/api/v1/xus/download

Field	Required	Description
`name`	yes	Exact firmware name, as returned by `/list` (≤ 255 chars).
`ttl`	no	Download-link lifetime in seconds, `60`–`604800`. Default 86400 (24 hours).

curl -s "https://mbcare.ru/api/v1/xus/download?name=2239020042_001-SMR-20260708_1212.zip" \
  -H "Authorization: Bearer $MBXUS_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "name": "2239020042_001-SMR-20260708_1212.zip",
  "downloadURL": "https://mbcare.ru/prod/symbolic/2239020042_001-SMR-20260708_1212.zip?…",
  "zipFileSize": 2492
}

downloadURL points at your own domain and is valid for ttl seconds (24 hours by default). Fetch it with a plain GET — no API key needed on that URL — and you receive the file. The upstream storage host is never exposed.

How the quota is charged

One file · one key · one UTC day. Issuing a /download link charges 1 against the daily limit.
Asking for the same file again the same day — retry, resume, a fresh link — does not count again.
/list never counts. Browsing the catalog is free.

6. Errors

Every error has the shape:

{ "ok": false, "code": "file_not_found", "error": "human-readable message", "requestId": "req_…" }

HTTP	code	Meaning
401	`missing_api_key` / `invalid_api_key`	No key, or malformed / unknown key.
403	`key_disabled` / `key_revoked` / `customer_disabled`	Key or account is not active.
403	`ip_not_allowed`	Caller IP is not in the key's allowed list. Response includes `seenIp`.
403	`no_access` / `access_expired`	The account has no XUS API subscription / it has ended.
403	`scope_missing`	The key is not permitted for this endpoint.
429	`daily_limit_reached`	Daily download quota spent. Resets at 00:00 UTC.
429	`rate_limited` / `ip_rate_limited`	More than 60 requests in a minute for this key / this IP.
400	`missing_name` / `invalid_name` / `invalid_query` / `invalid_cursor`	Bad input.
404	`file_not_found` / `no_download_link`	No firmware matches `name`.
405	`method_not_allowed`	Use GET or POST.
500 / 503	`internal_error` / `service_unavailable`	Temporary server-side problem — retry with backoff.

7. Limits & good practice

Daily quota: 200 or 2000 downloads per day depending on your plan; resets at 00:00 UTC.
Burst limit: 60 requests per minute per key (and per IP). Respect Retry-After.
Cache /list; re-fetch only when total changes or on a schedule.
Reuse a download link for its whole ttl window instead of calling /download again — it will not re-charge for the same file that day, but it saves a request.
Retry 500 / 503 with exponential backoff; do not retry other 4xx.
Log the X-Request-Id of failed calls for support.

Need a key or a higher limit? Contact support.