# MoQ # Relays ## List relays `client.moq.relays.list(RelayListParamsparams, RequestOptionsoptions?): SinglePage` **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 - `params: RelayListParams` - `account_id: string` Path param: Cloudflare account identifier. - `asc?: boolean` Query param: Sort order by `created`. When true, results are returned oldest-first (ascending); otherwise newest-first (descending, the default). - `created_after?: string` Query param: 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?: string` Query param: 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?: number` Query param: Maximum number of relays to return per page. Values above the maximum are clamped to it rather than rejected. ### Returns - `RelayListResponse` Abbreviated relay for list responses. - `created: string` - `modified: string` - `name: string` - `uid: string` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const relayListResponse of client.moq.relays.list({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(relayListResponse.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 `client.moq.relays.get(stringrelayID, RelayGetParamsparams, RequestOptionsoptions?): RelayGetResponse` **get** `/accounts/{account_id}/moq/relays/{relay_id}` Retrieves a single MoQ relay including config and status. Tokens are NOT included. ### Parameters - `relayID: string` - `params: RelayGetParams` - `account_id: string` Cloudflare account identifier. ### Returns - `RelayGetResponse` Full relay details (no tokens). - `config: Config` - `upstreams?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `modified: string` - `name: string` - `uid: string` - `status?: "connected"` "connected" when active, omitted otherwise. - `"connected"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const relay = await client.moq.relays.get('a1b2c3d4e5f67890a1b2c3d4e5f67890', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(relay.uid); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "https://example.com" } ] } }, "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 `client.moq.relays.create(RelayCreateParamsparams, RequestOptionsoptions?): 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 always set to defaults (upstreams off) and cannot be supplied here — sending a non-empty `config` is rejected (21014); `null` or `{}` is accepted as absent. Use PUT to configure the relay after it exists. ### Parameters - `params: RelayCreateParams` - `account_id: string` Path param: Cloudflare account identifier. - `name: string` Body param: Human-readable name for the relay. ### Returns - `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?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `issuers: Array` Token collection (discriminated union on `type`). On create this holds the auto-created default pair, each including its one-time secret. - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` - `modified: string` - `name: string` - `uid: string` Server-generated unique identifier (32 hex chars). ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const relay = await client.moq.relays.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', name: 'Production Live Stream', }); console.log(relay.uid); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "https://example.com" } ] } }, "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 `client.moq.relays.update(stringrelayID, RelayUpdateParamsparams, RequestOptionsoptions?): RelayUpdateResponse` **put** `/accounts/{account_id}/moq/relays/{relay_id}` Updates a relay's name and/or configuration. The relay ID goes in the URL path — `PUT /accounts/{account_id}/moq/relays/{relay_id}` — not the request body; there is no collection-level update endpoint. This is also the only way to set a relay's config (config cannot be set at create time). Partial updates: omitted fields are preserved; config sub-objects replace as whole objects when present. ### Parameters - `relayID: string` - `params: RelayUpdateParams` - `account_id: string` Path param: Cloudflare account identifier. - `config?: Config` Body param - `upstreams?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `name?: string` Body param ### Returns - `RelayUpdateResponse` Full relay details (no tokens). - `config: Config` - `upstreams?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `modified: string` - `name: string` - `uid: string` - `status?: "connected"` "connected" when active, omitted otherwise. - `"connected"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const relay = await client.moq.relays.update('a1b2c3d4e5f67890a1b2c3d4e5f67890', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(relay.uid); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "config": { "upstreams": { "enabled": true, "upstreams": [ { "url": "https://example.com" } ] } }, "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 `client.moq.relays.delete(stringrelayID, RelayDeleteParamsparams, RequestOptionsoptions?): RelayDeleteResponse | null` **delete** `/accounts/{account_id}/moq/relays/{relay_id}` Soft-deletes a MoQ relay. The relay ID goes in the URL path — `DELETE /accounts/{account_id}/moq/relays/{relay_id}` — not the request body; there is no collection-level delete endpoint. ### Parameters - `relayID: string` - `params: RelayDeleteParams` - `account_id: string` Cloudflare account identifier. ### Returns - `RelayDeleteResponse = unknown` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const relay = await client.moq.relays.delete('a1b2c3d4e5f67890a1b2c3d4e5f67890', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(relay); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": {} } ``` ## Domain Types ### Relay List Response - `RelayListResponse` Abbreviated relay for list responses. - `created: string` - `modified: string` - `name: string` - `uid: string` ### Relay Get Response - `RelayGetResponse` Full relay details (no tokens). - `config: Config` - `upstreams?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `modified: string` - `name: string` - `uid: string` - `status?: "connected"` "connected" when active, omitted otherwise. - `"connected"` ### Relay Create Response - `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?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `issuers: Array` Token collection (discriminated union on `type`). On create this holds the auto-created default pair, each including its one-time secret. - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` - `modified: string` - `name: string` - `uid: string` Server-generated unique identifier (32 hex chars). ### Relay Update Response - `RelayUpdateResponse` Full relay details (no tokens). - `config: Config` - `upstreams?: Upstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `enabled?: boolean` - `upstreams?: Array` 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: string` Upstream MOQT server publisher URL. Must be an absolute URL with a host and a scheme the relay can dial: moqt:// (raw QUIC) or https:// (WebTransport). Validated on update (PUT); rejected with 21013. - `created: string` - `modified: string` - `name: string` - `uid: string` - `status?: "connected"` "connected" when active, omitted otherwise. - `"connected"` ### Relay Delete Response - `RelayDeleteResponse = unknown` # Tokens ## Create a token `client.moq.relays.tokens.create(stringrelayID, TokenCreateParamsparams, RequestOptionsoptions?): 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 - `relayID: string` - `params: TokenCreateParams` - `account_id: string` Path param: Cloudflare account identifier. - `operations: Array<"publish" | "subscribe">` Body param: Non-empty subset of the V1 roles the token is allowed to perform. Signed into the token. - `"publish"` - `"subscribe"` - `expires?: string` Body param: Optional expiry (RFC 3339). Defaults to 1 year from creation; rejected if more than 1 year in the future. - `label?: string` Body param: Optional, customer-set label. ### Returns - `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: Array` - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const token = await client.moq.relays.tokens.create('a1b2c3d4e5f67890a1b2c3d4e5f67890', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', operations: ['publish', 'subscribe'], }); console.log(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 `client.moq.relays.tokens.list(stringrelayID, TokenListParamsparams, RequestOptionsoptions?): TokenListResponse` **get** `/accounts/{account_id}/moq/relays/{relay_id}/tokens` Returns metadata for every token the relay accepts. Secrets are never returned, so a token that has been lost cannot be recovered here. There is no expiry filter: compare each token's `expires` to the current time to tell which ones have lapsed. ### Parameters - `relayID: string` - `params: TokenListParams` - `account_id: string` Cloudflare account identifier. ### Returns - `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: Array` - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const tokens = await client.moq.relays.tokens.list('a1b2c3d4e5f67890a1b2c3d4e5f67890', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(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 `client.moq.relays.tokens.delete(stringjti, TokenDeleteParamsparams, RequestOptionsoptions?): TokenDeleteResponse` **delete** `/accounts/{account_id}/moq/relays/{relay_id}/tokens/{jti}` Revokes a token by removing it from the set the relay accepts. Relays cache that set, so revocation takes effect within seconds rather than instantly, and connections already established with the token are not closed. Revoking an unknown token succeeds, so the call is idempotent. ### Parameters - `jti: string` - `params: TokenDeleteParams` - `account_id: string` Cloudflare account identifier. - `relay_id: string` Relay unique identifier (32 hex characters). ### Returns - `TokenDeleteResponse` - `errors: Array` - `code?: number` - `message?: string` - `messages: Array` - `code?: number` - `message?: string` - `success: boolean` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const token = await client.moq.relays.tokens.delete('f3a1b2c3d4e5f67890a1b2c3d4e5f678', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', relay_id: 'a1b2c3d4e5f67890a1b2c3d4e5f67890', }); console.log(token.errors); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true } ``` ## Domain Types ### Token Create Response - `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: Array` - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` ### Token List Response - `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: Array` - `cloudflare_tokens: Array` Always present ([] when empty). - `created: string` - `expires: string` Mandatory; no more than 1 year after `created`. - `jti: string` Token identity and registry key (32 hex chars). - `operations: Array<"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?: string` Optional, customer-set. - `secret?: string` The signed JWT. Present ONLY in create / auto-create responses (shown once); never returned by list, never stored. - `issuer: "cloudflare"` - `"cloudflare"` - `type: "cloudflare_jwt"` - `"cloudflare_jwt"` ### Token Delete Response - `TokenDeleteResponse` - `errors: Array` - `code?: number` - `message?: string` - `messages: Array` - `code?: number` - `message?: string` - `success: boolean`