Request Models¶

Request body models used by subscription, source, and provider endpoints. All are Pydantic models with BaseModelConfig as their base (str_strip_whitespace=True, populate_by_name=True, use_enum_values=True). For admin-only request models, see Admin Models.

SourceCreateRequest¶

Used within SourcesAddRequest, SourcesReplaceRequest, and SubscriptionCreateRequest.

class SourceCreateRequest(BaseModelConfig):
    data: str
    is_hidden: bool | None = None
    max_depth: int | None = None  # 0-3

Also accepted as a plain string wherever a list of sources is expected (e.g. "vless://..." instead of {"data": "vless://..."}) — normalized to the object form before validation via a field_validator.

SubscriptionCreateRequest¶

class SubscriptionCreateRequest(BaseModelConfig):
    name: str
    description: str | None = None
    sources: list[SourceCreateRequest] = []

SubscriptionUpdateRequest¶

class SubscriptionUpdateRequest(BaseModelConfig):
    name: str | None = None
    description: str | None = None

Both fields are independently optional — there is no cross-field validator requiring at least one to be set.

SourcesAddRequest¶

class SourcesAddRequest(BaseModelConfig):
    sources: list[SourceCreateRequest]  # min 1, max settings.max_sources_per_subscription

Same normalization/deduplication as SubscriptionCreateRequest.sources, but with a hard minimum: the request itself requires min_length=1, and deduplication down to an empty list raises a validation error.

SourcesReplaceRequest¶

class SourcesReplaceRequest(BaseModelConfig):
    sources: list[SourceCreateRequest] = []  # max settings.max_sources_per_subscription

Same shape as SourcesAddRequest, except an empty list is explicitly allowed (default_factory=list, no minimum) — this is what lets Replace All Sources clear every source in one call.

SourcesRemoveRequest¶

class SourcesRemoveRequest(BaseModelConfig):
    source_ids: list[str]  # min 1 item, each HASH_LENGTH chars

IDs are deduplicated (preserving first occurrence) before the minimum-length check; an empty result raises a validation error.

SourceUpdateRequest¶

Backs Update Config. Only fields explicitly present and non-null in the request are applied; everything else is left unchanged server-side.

class SourceUpdateRequest(BaseModelConfig):
    config_hash: str      # alias: config_id
    comment: str | None = None
    is_hidden: bool | None = None
    max_depth: int | None = None  # 0-3

CommentUpdateRequest ^Deprecated¶

Backs the deprecated Update Config Comment endpoint. The class itself is marked @deprecated in source (typing_extensions.deprecated), which some type checkers and IDEs will surface as a warning if you construct it directly.

class CommentUpdateRequest(BaseModelConfig):
    config_hash: str      # alias: config_id
    comment: str | None = None

Same config_hash/config_id aliasing as SourceUpdateRequest.

ProviderConnectionRequest¶

class ProviderConnectionRequest(BaseModelConfig):
    user_id: int  # 1 to 999,999,999,999

Underlies the path-parameter-driven provider endpoints (Request Access to User, etc.) — in practice user_id arrives via the URL path on those routes rather than this model being used as a JSON body directly, but it defines the same validation constraints.