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.