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 (it needs an active subscription and is limited to 10 requests per minute per key).
Repeated requests with a missing or unknown key are blocked: 20 such 401 responses within 5 minutes from one IP ban that IP for all sites of this service. Check that your client sends the key correctly before running a loop.
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://mb-solution.org/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); needs an active subscription, 10/min	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://mb-solution.org/api/v1/seed/quota

curl -s https://mb-solution.org/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://mb-solution.org/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://mb-solution.org/api/v1/seed/catalog \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

# conditional:
curl -s -X POST https://mb-solution.org/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",
      "SelectorMatch": null
    }
  ],
  "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`	Software identifier, for example `1979021500` or `IC907_Low_SW1_9079020707`; `null` when absent. Calculate accepts the full value or its firmware number.
`SelectorMatch`	Selector expression, for example `ActiveDiagnosticInformation_Read.Identification=8700,8600`; `null` when absent. The comma separates alternative identification codes.

Identify the algorithm by ecuName, accessLevel, seedLength, keyLength and software (full value or firmware number). For SelectorMatch, send the single identification code read from the ECU, not the catalog expression.

6. POST /calculate

POSThttps://mb-solution.org/api/v1/seed/calculate

Calculate a key by ECU facts: send the ECU name, access level, seed/key lengths, optional software and identification code, and the seed.

Request fields

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	Full catalog string or firmware number, for example `"IC222_SW2_2059021304"`, `"2059021304"` or `"000A"`. String of 1–255 characters without control characters. Omit, send `null` or an empty string to match rows without software.
`SelectorMatch`	no	One 4-character hex code as a string, for example `"8700"` or `"8600"`. Case-insensitive; preserve leading zeros. No prefix or comma-separated list. `selectorMatch` is also accepted. Omit, send `null` or an empty string for the default selection.
`catalogVersion`	no	The catalog `version` you built against — `409 catalog_outdated` on mismatch.

Software matching ignores ASCII letter case and preserves leading zeros. A complete value match takes priority. Otherwise, a short hexadecimal or decimal firmware number matches the entire token immediately after SW_, SW0_, SW1_, SW2_, etc.; partial substrings do not match. Selector selection then runs within the software matches. The response contains the full stored software value.

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://mb-solution.org/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"}'

When SelectorMatch is supplied, a row containing that code takes priority. For Identification=8700,8600, either "8700" or "8600" selects that row. If no code matches, a row with an empty selector is used. If none exists, the row containing the lowest numeric HEX code is selected, considering every comma-separated code: 00FF is lower than 1000. All choices require the same ECU, level, lengths and software. The API returns 404 definition_not_found only if no eligible row exists. Omitting the selector uses the default primary row.

Example request with an identification code (use ECU facts from your catalog row):

{
  "ecuName": "YOUR_ECU",
  "accessLevel": 17,
  "seedLength": 8,
  "keyLength": 8,
  "software": null,
  "SelectorMatch": "8700",
  "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": "groupPrimary",
  "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.

matchedBy is selector for an identification-code match, selectorFallback for an empty-selector row, selectorLowest for the lowest HEX code, or groupPrimary for the default selection.

7. GET /benchmark

GEThttps://mb-solution.org/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. Requires an API key with an active Seed-Key subscription. Limit: 10 requests per minute per key; exceeding it returns 429 rate_limited with Retry-After.

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

curl -s https://mb-solution.org/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 (10 for `/benchmark`).
401	`missing_api_key` / `invalid_api_key`	No key, or a malformed / unknown key. Twenty of these from one IP within 5 minutes block the IP.
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_catalog_version`	Bad input.
400	`invalid_ecu_name` / `invalid_access_level` / `invalid_length` / `invalid_software` / `invalid_selector_match`	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.
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 (10 per minute for /benchmark). 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 + SelectorMatch + 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.