Response Models¶

Response models for subscription, source, provider-connection, and user endpoints. For admin-only response models, see Admin Models.

SourceOut¶

An individual, resolved source within a subscription's sources list.

class SourceOut(BaseModelConfig):
    id: str                      # 32 hex chars
    source_type: SourceType
    data: str
    order_index: int             # >= 0
    is_hidden: bool = False
    max_depth: int = 3           # 0-3, default settings.max_nesting_depth
    created_at: datetime
    updated_at: datetime

What data contains, by source_type (per the server's own convert_sources_to_out logic):

• config: the raw proxy config string, with #{comment} appended if a comment is set on this source within this subscription (comments are per-subscription, so the same underlying config can carry different comments in different subscriptions).
• external_url: the external subscription URL, unchanged.
• internal_token: reconstructed as https://{domain}/sub/{token} (i.e. you get back a full public-subscription URL, not a bare token) — {domain} is the server's configured DOMAIN setting.

SubscriptionResponse¶

Full subscription detail, returned by create/get/update and every source-mutation endpoint.

class SubscriptionResponse(SubscriptionBase):
    sources: list[SourceOut] = []

Where SubscriptionBase provides:

SubscriptionListItem¶

Identical to SubscriptionBase above (i.e. every SubscriptionResponse field except sources) — returned by the list-subscriptions endpoint. Fetch a subscription individually via Get Subscription Details to see its resolved source list.

RefreshSubscriptionResponse¶

class RefreshSubscriptionResponse(BaseModelConfig):
    refreshed: int = 0
    failed: int = 0
    skipped: int = 0
    message: str | None = None
    errors: list[str] = []

    @computed_field
    def total(self) -> int:
        return self.refreshed + self.failed + self.skipped

MeResponse¶

class MeResponse(BaseModelConfig):
    user_id: int
    is_active: bool

Deliberately minimal — per the source's own docstring, this exposes only information relevant to the self-service API and does not include internal identifiers like user_hash.

ConnectionResponse¶

A single provider connection, from the connected user's point of view.

class ConnectionResponse(BaseModelConfig):
    provider_name: str          # 4-16 chars
    provider_url: str | None    # max 255 chars
    is_authorized: bool
    status: ProviderAuthorizationStatus | None = None

is_authorized is true exactly when status == ProviderAuthorizationStatus.APPROVED — it's derived at response-construction time, not an independently stored field.

ConnectionsResponse¶

class ConnectionsResponse(BaseModelConfig):
    connections: list[ConnectionResponse]

Returned by User Self-Service → List My Connections and the admin equivalent, Admin → List User's Connections.

ProviderConnectionResponse¶

The provider-side view of a connection (as opposed to ConnectionResponse, which is the user-side view of the same relationship).

class ProviderConnectionResponse(BaseModelConfig):
    user_id: int
    status: ProviderAuthorizationStatus

ProviderConnectionCreateResponse¶

Extends ProviderConnectionResponse with an optional connection link.

class ProviderConnectionCreateResponse(ProviderConnectionResponse):
    connection_link: str | None

connection_link is only non-null when Request Access to User had to fall back to the HMAC invite-link flow. See Authentication → Provider Connection-Invite HMAC.

ProviderConnectionDeleteResponse¶

Response returned after deleting a provider connection.

class ProviderConnectionDeleteResponse(BaseModelConfig):
    detail: str

ProviderInfoResponse¶

class ProviderInfoResponse(BaseModelConfig):
    provider_name: str    # 4-16 chars
    provider_url: str     # max 255 chars, required (not optional here)

A smaller, provider-facing shape distinct from the admin-only ProviderResponse — notably, provider_url is required (non-optional) on this model, unlike most other places provider_url appears.