Spec Patches
Patches applied on top of upstream Marzban's OpenAPI spec, and why — so you know when a type differs from what the panel actually returns.
MarzbanSDK vendors packages/sdk/openapi/openapi.json in the repository instead of fetching Marzban's spec at build time (see ADR-0003), and hand-patches schemas that upstream leaves under-specified. Every patch currently applied is listed here.
Under-specified schemas no longer drop fields on parse
Several upstream schemas are declared with no properties at all — proxy settings, parts of the core config. kubb generates these as an empty Zod object, and Zod's default strip mode silently drops every key when parsing a real payload:
getCoreConfig()/modifyCoreConfig()returned{}instead of the actual Xray core config.- Every user response's
proxiesfield returned{}instead of the per-protocol settings.
Fix (2026-08-12): patched the schema to additionalProperties: true, so kubb emits .catchall(z.()) instead of a key-dropping strict object.
| Schema | Where it shows up |
|---|---|
| user.proxies[protocol] on every endpoint that returns a user — see the patched-endpoint badges on the OpenAPI Spec page |
| Core config (GET response) | GET /api/core/config |
| Core config (PUT request + response) | PUT /api/core/config |
Pinned by gen-regression.test.ts — a future pnpm --filter marzban-sdk codegen run that reverts this fails the test suite instead of shipping silently-truncated data.
OpenAPI Spec
The exact schema MarzbanSDK is generated from — patched where upstream Marzban's spec is under-specified. Browse the endpoints below or download the file directly.
Contributing
How to contribute to MarzbanSDK — reporting bugs, submitting PRs, and development setup in the pnpm/Turborepo monorepo.