Seed-Key API v1

Programmatic access to the Seed → Key calculator. Access is granted per account and shares the daily limit and validity window of that account's Seed-Key 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 mbseed_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978
X-API-Key: mbseed_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 single key type — it can call every endpoint. Use /benchmark to test latency without spending quota.
• 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 GET /catalog and GET /benchmark that carry no body; some requests are rejected without it.

2. Base URL & endpoints

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

Endpoint	Method	Purpose	Metered
/quota	GET	Current access window and daily usage	no
/catalog	GET / POST	ECU catalog + current catalog version	no
/calculate	POST	Calculate a key for a seed	yes — 1 per success
/benchmark	GET / POST	Round-trip latency probe (returns an all-zero key)	no

3. Response headers

Header	Meaning
X-Request-Id	Unique id for the request — quote it in support tickets.
X-Seed-Quota-Limit	Daily calculation limit for the account.
X-Seed-Quota-Remaining	Calculations left until 00:00 UTC.
X-Seed-Quota-Reset	Unix timestamp of the next quota reset.
Retry-After	On 429 — seconds to wait before retrying.

4. GET /quota

GEThttps://mbcare.ru/api/v1/seed/quota

curl -s https://mbcare.ru/api/v1/seed/quota \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "allowed": true,
  "code": "ok",
  "quota": {
    "dailyLimit": 200,
    "used": 4,
    "remaining": 196,
    "accessUntil": "2026-12-31T20:00:00Z",
    "resetAt": "2026-09-05T00:00:00Z"
  },
  "requestId": "req_1a2b3c4d5e6f7a8b90"
}

5. GET /catalog

GEThttps://mbcare.ru/api/v1/seed/catalog

Returns every supported ECU algorithm plus a version hash for the whole catalog. Pass your last known hash as knownVersion to get {"unchanged": true} with no items when nothing has changed.

curl -s https://mbcare.ru/api/v1/seed/catalog \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

# conditional:
curl -s -X POST https://mbcare.ru/api/v1/seed/catalog \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knownVersion":"<64-hex>"}'

{
  "ok": true,
  "schemaVersion": 1,
  "version": "9c1f...<64-hex>",
  "count": 4445,
  "unchanged": false,
  "items": [
    {
      "definitionId": "3f8a...<64-hex>",
      "ecuName": "IC_204",
      "accessLevel": 1,
      "seedLength": 8,
      "keyLength": 8,
      "software": "1979021500"
    }
  ],
  "requestId": "req_…"
}

Item field	Meaning
definitionId	Opaque 64-hex id. Stable, but can be absent for rows served from the file fallback — prefer matching on ECU facts.
ecuName	ECU / control-unit name.
accessLevel	Access level (integer).
seedLength / keyLength	Byte lengths of the seed and the resulting key.
software	Firmware number for the IC204/IC213/… families; null otherwise.

To find your algorithm again after a catalog update, match locally on ecuName + accessLevel + software + seedLength + keyLength — and pass exactly those to /calculate.

6. POST /calculate

POSThttps://mbcare.ru/api/v1/seed/calculate

Two ways to identify the algorithm. By ECU facts is recommended — it does not depend on definitionId and keeps working across catalog updates.

6a. By ECU facts

Field	Required	Description
ecuName	yes	1–64 printable ASCII, from /catalog (upper-cased server-side).
accessLevel	yes	Integer 0–1024.
seedLength	yes	1–512; must equal the byte length of seed.
keyLength	yes	1–512.
seed	yes	Hex string (even length, ≤ 512 chars). Spaces, -, : are stripped.
software	no	1–32 digits. Omit to match the non-firmware rows.
catalogVersion	no	The catalog version you built against — 409 catalog_outdated on mismatch.

If several rows share the same facts the response returns the primary one with candidates > 1 — contact support if you hit an ambiguous ECU.

curl -s -X POST https://mbcare.ru/api/v1/seed/calculate \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ecuName":"IC_204","accessLevel":1,"seedLength":8,"keyLength":8,
       "software":"1979021500","seed":"A1B2C3D4A1B2C3D4"}'

6b. By definitionId

Field	Required	Description
definitionId	yes	64-hex id from /catalog (not all-zero).
seed	yes	Hex; byte length must equal the definition's seedLength.
catalogVersion	no	As above.

curl -s -X POST https://mbcare.ru/api/v1/seed/calculate \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"definitionId":"3f8a...<64-hex>","seed":"A1B2C3D4A1B2C3D4"}'

Response

{
  "ok": true,
  "schemaVersion": 1,
  "catalogVersion": "9c1f...<64-hex>",
  "definitionId": "3f8a...<64-hex>",
  "ecuName": "IC_204",
  "accessLevel": 1,
  "seedLength": 8,
  "keyLength": 8,
  "software": "1979021500",
  "matchedBy": "definitionId",       // "definitionId" | "groupPrimary" | "benchmark"
  "candidates": 1,
  "key": "1122334455667788",
  "quota": { "dailyLimit": 200, "used": 5, "remaining": 195,
             "accessUntil": "2026-12-31T20:00:00Z", "resetAt": "2026-09-05T00:00:00Z" },
  "requestId": "req_…"
}

The daily counter is incremented only on a successful calculation. key is upper-case hex.

7. GET /benchmark

GEThttps://mbcare.ru/api/v1/seed/benchmark

Runs the real database read path on the calculation server and returns an all-zero key, so you can measure end-to-end latency without spending quota or needing an active subscription. Any key can call it.

Field	Required	Description
seed	no	Any valid hex; defaults to A5A5A5A5A5A5A5A5.
keyLength	no	1–512; length of the returned zero key.

curl -s https://mbcare.ru/api/v1/seed/benchmark \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "matchedBy": "benchmark",
  "upstreamMs": 41.7,
  "catalogVersion": "9c1f...<64-hex>",
  "keyLength": 8,
  "key": "0000000000000000",
  "probe": { "ecuName": "IC_204", "accessLevel": 1, "seedLength": 8, "software": "1979021500" },
  "requestId": "req_…"
}

8. Errors

Every error has the shape:

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

HTTP	code	Meaning
401	missing_api_key / invalid_api_key	No key, or malformed / unknown key.
403	key_revoked / key_disabled / customer_disabled	Key or account is not active.
403	ip_not_allowed	Caller IP is not in the key's allowed list.
403	access_expired / no_access	Subscription ended / the account has no Seed-Key subscription.
403	scope_missing	The key is not permitted for this endpoint.
429	daily_limit_reached	Daily quota spent. Retry-After = seconds to 00:00 UTC.
429	rate_limited	More than 60 requests in a minute for this key.
429	upstream_rate_limited	The calculation service is briefly saturated (a limit shared by all API clients). Retry shortly.
400	invalid_json / invalid_seed / invalid_definition / invalid_catalog_version	Bad input.
400	invalid_ecu_name / invalid_access_level / invalid_length / invalid_software	Bad ECU-facts field.
400	seed_length_mismatch	Seed byte length ≠ the algorithm's. Response includes expectedLength.
404	definition_not_found	No algorithm matches the given facts / definitionId.
405	method_not_allowed	Wrong HTTP method for the endpoint.
409	catalog_outdated	Reload /catalog; the response includes currentVersion.
502	upstream_unavailable / upstream_auth_failed	Calculation service unreachable or gateway misconfigured.
503	service_unavailable / resolve_unavailable / benchmark_unavailable	Temporary server-side / catalog-database problem — retry with backoff.

9. Limits & good practice

• Daily quota is shared with the website Seed-Key page — both draw from the same bucket, resetting at 00:00 UTC.
• Burst limit: 60 requests per minute per key. Respect Retry-After.
• The calculation service also has a short shared budget across all API clients; a burst can yield 429 upstream_rate_limited — retry with a small backoff.
• Cache /catalog; refresh it only on 409 catalog_outdated or on a schedule (e.g. daily). Match algorithms on ecuName + accessLevel + software + seedLength + keyLength.
• Retry 502 / 503 / upstream_rate_limited with exponential backoff; do not retry other 4xx except 409 (after reloading the catalog).
• Log the X-Request-Id of failed calls for support.
• schemaVersion in every success body only increments on a breaking change (a field removed, renamed, or retyped); new fields may appear without a bump, so read fields by name.

Need a key or a higher limit? Contact support.