# Relays ## List relays `moq.relays.list(RelayListParams**kwargs) -> SyncSinglePage[RelayListResponse]` **get** `/accounts/{account_id}/moq/relays` Lists all MoQ relays for the account. Returns only metadata. Config, status, and tokens are omitted. Results are cursor-paginated (keyset on the `created` timestamp). Use `created_before` / `created_after` with the `created` value of the first/last item in a page to fetch the adjacent page. `result_info` reports the page `count` and the `total` matching the cursor filters. ### Parameters - `account_id: str` Cloudflare account identifier. - `asc: Optional[bool]` Sort order by `created`. When true, results are returned oldest-first (ascending); otherwise newest-first (descending, the default). - `created_after: Optional[Union[str, datetime]]` Cursor for pagination. Returns relays created strictly after this RFC 3339 timestamp (typically the `created` value of the last item on the current page, to fetch the next page). - `created_before: Optional[Union[str, datetime]]` Cursor for pagination. Returns relays created strictly before this RFC 3339 timestamp (typically the `created` value of the first item on the current page, to fetch the previous page). - `per_page: Optional[int]` Maximum number of relays to return per page. ### Returns - `class RelayListResponse: …` Abbreviated relay for list responses. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.moq.relays.list( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) page = page.result[0] print(page.uid) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": [ { "created": "2019-12-27T18:11:19.117Z", "modified": "2019-12-27T18:11:19.117Z", "name": "name", "uid": "a1b2c3d4e5f67890a1b2c3d4e5f67890" } ], "result_info": { "count": 0, "total": 0 } } ``` ## Get a relay `moq.relays.get(strrelay_id, RelayGetParams**kwargs) -> RelayGetResponse` **get** `/accounts/{account_id}/moq/relays/{relay_id}` Retrieves a single MoQ relay including config and status. Tokens are NOT included. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` ### Returns - `class RelayGetResponse: …` Full relay details (no tokens). - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` - `status: Optional[Literal["connected"]]` "connected" when active, omitted otherwise. - `"connected"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) relay = client.moq.relays.get( relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(relay.uid) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "url" } ] } }, "created": "2019-12-27T18:11:19.117Z", "modified": "2019-12-27T18:11:19.117Z", "name": "Production Live Stream", "uid": "a1b2c3d4e5f67890a1b2c3d4e5f67890", "status": "connected" } } ``` ## Create a relay `moq.relays.create(RelayCreateParams**kwargs) -> RelayCreateResponse` **post** `/accounts/{account_id}/moq/relays` Provisions a new MoQ relay instance. Auto-creates a publish+subscribe token and a subscribe-only token. Token values are included in the response (shown once). Config is set to defaults (upstreams off). Use PUT to modify. ### Parameters - `account_id: str` Cloudflare account identifier. - `name: str` Human-readable name for the relay. ### Returns - `class RelayCreateResponse: …` Relay with its auto-created default token pair (one full-access [publish, subscribe] and one [subscribe]-only), each with its one-time secret, wrapped in the issuers envelope. - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `issuers: List[Issuer]` Token collection (discriminated union on `type`). On create this holds the auto-created default pair, each including its one-time secret. - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` - `modified: datetime` - `name: str` - `uid: str` Server-generated unique identifier (32 hex chars). ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) relay = client.moq.relays.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", name="Production Live Stream", ) print(relay.uid) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "url" } ] } }, "created": "2019-12-27T18:11:19.117Z", "issuers": [ { "cloudflare_tokens": [ { "created": "2019-12-27T18:11:19.117Z", "expires": "2019-12-27T18:11:19.117Z", "jti": "f3a1b2c3d4e5f67890a1b2c3d4e5f678", "operations": [ "publish", "subscribe" ], "label": "primary-encoder", "secret": "eyJhbGciOiJFZDI1NTE5..." } ], "issuer": "cloudflare", "type": "cloudflare_jwt" } ], "modified": "2019-12-27T18:11:19.117Z", "name": "Production Live Stream", "uid": "a1b2c3d4e5f67890a1b2c3d4e5f67890" } } ``` ## Update a relay `moq.relays.update(strrelay_id, RelayUpdateParams**kwargs) -> RelayUpdateResponse` **put** `/accounts/{account_id}/moq/relays/{relay_id}` Updates a relay's name and/or configuration. Partial updates: omitted fields are preserved. Config sub-objects replace as whole objects when present. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` - `config: Optional[Config]` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[Iterable[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `name: Optional[str]` ### Returns - `class RelayUpdateResponse: …` Full relay details (no tokens). - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` - `status: Optional[Literal["connected"]]` "connected" when active, omitted otherwise. - `"connected"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) relay = client.moq.relays.update( relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(relay.uid) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "url" } ] } }, "created": "2019-12-27T18:11:19.117Z", "modified": "2019-12-27T18:11:19.117Z", "name": "Production Live Stream", "uid": "a1b2c3d4e5f67890a1b2c3d4e5f67890", "status": "connected" } } ``` ## Delete a relay `moq.relays.delete(strrelay_id, RelayDeleteParams**kwargs) -> object` **delete** `/accounts/{account_id}/moq/relays/{relay_id}` Soft-deletes a MoQ relay. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) relay = client.moq.relays.delete( relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(relay) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": {} } ``` ## Domain Types ### Relay List Response - `class RelayListResponse: …` Abbreviated relay for list responses. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` ### Relay Get Response - `class RelayGetResponse: …` Full relay details (no tokens). - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` - `status: Optional[Literal["connected"]]` "connected" when active, omitted otherwise. - `"connected"` ### Relay Create Response - `class RelayCreateResponse: …` Relay with its auto-created default token pair (one full-access [publish, subscribe] and one [subscribe]-only), each with its one-time secret, wrapped in the issuers envelope. - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `issuers: List[Issuer]` Token collection (discriminated union on `type`). On create this holds the auto-created default pair, each including its one-time secret. - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` - `modified: datetime` - `name: str` - `uid: str` Server-generated unique identifier (32 hex chars). ### Relay Update Response - `class RelayUpdateResponse: …` Full relay details (no tokens). - `config: Config` - `upstreams: Optional[ConfigUpstreams]` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled: Optional[bool]` - `upstreams: Optional[List[ConfigUpstreamsUpstream]]` Ordered list of upstream MOQT server publishers. Each entry is an object (not a bare string) so per-upstream configuration can be added in the future without another breaking change. - `url: Optional[str]` Upstream MOQT server publisher URL. - `created: datetime` - `modified: datetime` - `name: str` - `uid: str` - `status: Optional[Literal["connected"]]` "connected" when active, omitted otherwise. - `"connected"` # Tokens ## Create a token `moq.relays.tokens.create(strrelay_id, TokenCreateParams**kwargs) -> TokenCreateResponse` **post** `/accounts/{account_id}/moq/relays/{relay_id}/tokens` Mints a new relay-scoped token and adds it to the relay's accepted-auth registry. The token value (secret) is shown once in the response. A relay may hold up to 10 tokens; creating an 11th is rejected. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` - `operations: List[Literal["publish", "subscribe"]]` Non-empty subset of the V1 roles the token is allowed to perform. Signed into the token. - `"publish"` - `"subscribe"` - `expires: Optional[Union[str, datetime]]` Optional expiry (RFC 3339). Defaults to 1 year from creation; rejected if more than 1 year in the future. - `label: Optional[str]` Optional, customer-set label. ### Returns - `class TokenCreateResponse: …` A relay's token collection, keyed on issuer `type` (a discriminated union). V1 ships exactly one arm (`cloudflare_jwt`). Clients iterate `issuers`, switch on `type`, and ignore unknown types — that contract is what makes adding or removing an arm non-breaking. - `issuers: List[Issuer]` - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) token = client.moq.relays.tokens.create( relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", account_id="023e105f4ecef8ad9ca31a8372d0c353", operations=["publish", "subscribe"], ) print(token.issuers) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "issuers": [ { "cloudflare_tokens": [ { "created": "2019-12-27T18:11:19.117Z", "expires": "2019-12-27T18:11:19.117Z", "jti": "f3a1b2c3d4e5f67890a1b2c3d4e5f678", "operations": [ "publish", "subscribe" ], "label": "primary-encoder", "secret": "eyJhbGciOiJFZDI1NTE5..." } ], "issuer": "cloudflare", "type": "cloudflare_jwt" } ] } } ``` ## List tokens `moq.relays.tokens.list(strrelay_id, TokenListParams**kwargs) -> TokenListResponse` **get** `/accounts/{account_id}/moq/relays/{relay_id}/tokens` Returns metadata for every token in the relay's registry. Secrets are never returned. The dashboard derives an `expired` flag by comparing each token's `expires` to the current time. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` ### Returns - `class TokenListResponse: …` A relay's token collection, keyed on issuer `type` (a discriminated union). V1 ships exactly one arm (`cloudflare_jwt`). Clients iterate `issuers`, switch on `type`, and ignore unknown types — that contract is what makes adding or removing an arm non-breaking. - `issuers: List[Issuer]` - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) tokens = client.moq.relays.tokens.list( relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(tokens.issuers) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "issuers": [ { "cloudflare_tokens": [ { "created": "2019-12-27T18:11:19.117Z", "expires": "2019-12-27T18:11:19.117Z", "jti": "f3a1b2c3d4e5f67890a1b2c3d4e5f678", "operations": [ "publish", "subscribe" ], "label": "primary-encoder", "secret": "eyJhbGciOiJFZDI1NTE5..." } ], "issuer": "cloudflare", "type": "cloudflare_jwt" } ] } } ``` ## Revoke a token `moq.relays.tokens.delete(strjti, TokenDeleteParams**kwargs) -> TokenDeleteResponse` **delete** `/accounts/{account_id}/moq/relays/{relay_id}/tokens/{jti}` Revokes a token by removing it from the relay's registry. crique rejects the token within the cache TTL. Idempotent — revoking an unknown token succeeds. ### Parameters - `account_id: str` Cloudflare account identifier. - `relay_id: str` - `jti: str` ### Returns - `class TokenDeleteResponse: …` - `errors: List[Error]` - `code: Optional[int]` - `message: Optional[str]` - `messages: List[Message]` - `code: Optional[int]` - `message: Optional[str]` - `success: bool` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) token = client.moq.relays.tokens.delete( jti="f3a1b2c3d4e5f67890a1b2c3d4e5f678", account_id="023e105f4ecef8ad9ca31a8372d0c353", relay_id="a1b2c3d4e5f67890a1b2c3d4e5f67890", ) print(token.errors) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true } ``` ## Domain Types ### Token Create Response - `class TokenCreateResponse: …` A relay's token collection, keyed on issuer `type` (a discriminated union). V1 ships exactly one arm (`cloudflare_jwt`). Clients iterate `issuers`, switch on `type`, and ignore unknown types — that contract is what makes adding or removing an arm non-breaking. - `issuers: List[Issuer]` - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` ### Token List Response - `class TokenListResponse: …` A relay's token collection, keyed on issuer `type` (a discriminated union). V1 ships exactly one arm (`cloudflare_jwt`). Clients iterate `issuers`, switch on `type`, and ignore unknown types — that contract is what makes adding or removing an arm non-breaking. - `issuers: List[Issuer]` - `cloudflare_tokens: List[IssuerCloudflareToken]` Always present ([] when empty). - `created: datetime` - `expires: datetime` Mandatory; no more than 1 year after `created`. - `jti: str` Token identity and registry key (32 hex chars). - `operations: List[Literal["publish", "subscribe"]]` Signed allowlist of what the token may do. V1 coarse roles; the array form extends to fine-grained MoQT message names later without a breaking change. - `"publish"` - `"subscribe"` - `label: Optional[str]` Optional, customer-set. - `secret: Optional[str]` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: Literal["cloudflare"]` - `"cloudflare"` - `type: Literal["cloudflare_jwt"]` - `"cloudflare_jwt"` ### Token Delete Response - `class TokenDeleteResponse: …` - `errors: List[Error]` - `code: Optional[int]` - `message: Optional[str]` - `messages: List[Message]` - `code: Optional[int]` - `message: Optional[str]` - `success: bool`