# MoQ # Relays ## List relays `client.MoQ.Relays.List(ctx, params) (*SinglePage[RelayListResponse], error)` **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` - `AccountID param.Field[string]` Path param: Cloudflare account identifier. - `Asc param.Field[bool]` Query param: Sort order by `created`. When true, results are returned oldest-first (ascending); otherwise newest-first (descending, the default). - `CreatedAfter param.Field[Time]` 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). - `CreatedBefore param.Field[Time]` 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). - `PerPage param.Field[int64]` Query param: Maximum number of relays to return per page. ### Returns - `type RelayListResponse struct{…}` Abbreviated relay for list responses. - `Created Time` - `Modified Time` - `Name string` - `UID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.MoQ.Relays.List(context.TODO(), moq.RelayListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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(ctx, relayID, query) (*RelayGetResponse, error)` **get** `/accounts/{account_id}/moq/relays/{relay_id}` Retrieves a single MoQ relay including config and status. Tokens are NOT included. ### Parameters - `relayID string` - `query RelayGetParams` - `AccountID param.Field[string]` Cloudflare account identifier. ### Returns - `type RelayGetResponse struct{…}` Full relay details (no tokens). - `Config RelayGetResponseConfig` - `Upstreams RelayGetResponseConfigUpstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `Enabled bool` - `Upstreams []RelayGetResponseConfigUpstreamsUpstream` 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. - `Created Time` - `Modified Time` - `Name string` - `UID string` - `Status RelayGetResponseStatus` "connected" when active, omitted otherwise. - `const RelayGetResponseStatusConnected RelayGetResponseStatus = "connected"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) relay, err := client.MoQ.Relays.Get( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", moq.RelayGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.MoQ.Relays.New(ctx, params) (*RelayNewResponse, error)` **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 - `params RelayNewParams` - `AccountID param.Field[string]` Path param: Cloudflare account identifier. - `Name param.Field[string]` Body param: Human-readable name for the relay. ### Returns - `type RelayNewResponse struct{…}` 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 RelayNewResponseConfig` - `Upstreams RelayNewResponseConfigUpstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `Enabled bool` - `Upstreams []RelayNewResponseConfigUpstreamsUpstream` 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. - `Created Time` - `Issuers []RelayNewResponseIssuer` Token collection (discriminated union on `type`). On create this holds the auto-created default pair, each including its one-time secret. - `CloudflareTokens []RelayNewResponseIssuersCloudflareToken` Always present ([] when empty). - `Created Time` - `Expires Time` Mandatory; no more than 1 year after `created`. - `Jti string` Token identity and registry key (32 hex chars). - `Operations []RelayNewResponseIssuersCloudflareTokensOperation` 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. - `const RelayNewResponseIssuersCloudflareTokensOperationPublish RelayNewResponseIssuersCloudflareTokensOperation = "publish"` - `const RelayNewResponseIssuersCloudflareTokensOperationSubscribe RelayNewResponseIssuersCloudflareTokensOperation = "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 RelayNewResponseIssuersIssuer` - `const RelayNewResponseIssuersIssuerCloudflare RelayNewResponseIssuersIssuer = "cloudflare"` - `Type RelayNewResponseIssuersType` - `const RelayNewResponseIssuersTypeCloudflareJWT RelayNewResponseIssuersType = "cloudflare_jwt"` - `Modified Time` - `Name string` - `UID string` Server-generated unique identifier (32 hex chars). ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) relay, err := client.MoQ.Relays.New(context.TODO(), moq.RelayNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Name: cloudflare.F("Production Live Stream"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.MoQ.Relays.Update(ctx, relayID, params) (*RelayUpdateResponse, error)` **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 - `relayID string` - `params RelayUpdateParams` - `AccountID param.Field[string]` Path param: Cloudflare account identifier. - `Config param.Field[RelayUpdateParamsConfig]` Body param - `Upstreams RelayUpdateParamsConfigUpstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `Enabled bool` - `Upstreams []RelayUpdateParamsConfigUpstreamsUpstream` 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. - `Name param.Field[string]` Body param ### Returns - `type RelayUpdateResponse struct{…}` Full relay details (no tokens). - `Config RelayUpdateResponseConfig` - `Upstreams RelayUpdateResponseConfigUpstreams` Upstreams are external MOQT server publishers that a relay falls back to when it has no local publisher for a requested namespace/track. - `Enabled bool` - `Upstreams []RelayUpdateResponseConfigUpstreamsUpstream` 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. - `Created Time` - `Modified Time` - `Name string` - `UID string` - `Status RelayUpdateResponseStatus` "connected" when active, omitted otherwise. - `const RelayUpdateResponseStatusConnected RelayUpdateResponseStatus = "connected"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) relay, err := client.MoQ.Relays.Update( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", moq.RelayUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.MoQ.Relays.Delete(ctx, relayID, body) (*RelayDeleteResponse, error)` **delete** `/accounts/{account_id}/moq/relays/{relay_id}` Soft-deletes a MoQ relay. ### Parameters - `relayID string` - `body RelayDeleteParams` - `AccountID param.Field[string]` Cloudflare account identifier. ### Returns - `type RelayDeleteResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) relay, err := client.MoQ.Relays.Delete( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", moq.RelayDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", relay) } ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": {} } ``` # Tokens ## Create a token `client.MoQ.Relays.Tokens.New(ctx, relayID, params) (*RelayTokenNewResponse, error)` **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 RelayTokenNewParams` - `AccountID param.Field[string]` Path param: Cloudflare account identifier. - `Operations param.Field[[]RelayTokenNewParamsOperation]` Body param: Non-empty subset of the V1 roles the token is allowed to perform. Signed into the token. - `const RelayTokenNewParamsOperationPublish RelayTokenNewParamsOperation = "publish"` - `const RelayTokenNewParamsOperationSubscribe RelayTokenNewParamsOperation = "subscribe"` - `Expires param.Field[Time]` Body param: Optional expiry (RFC 3339). Defaults to 1 year from creation; rejected if more than 1 year in the future. - `Label param.Field[string]` Body param: Optional, customer-set label. ### Returns - `type RelayTokenNewResponse struct{…}` 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 []RelayTokenNewResponseIssuer` - `CloudflareTokens []RelayTokenNewResponseIssuersCloudflareToken` Always present ([] when empty). - `Created Time` - `Expires Time` Mandatory; no more than 1 year after `created`. - `Jti string` Token identity and registry key (32 hex chars). - `Operations []RelayTokenNewResponseIssuersCloudflareTokensOperation` 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. - `const RelayTokenNewResponseIssuersCloudflareTokensOperationPublish RelayTokenNewResponseIssuersCloudflareTokensOperation = "publish"` - `const RelayTokenNewResponseIssuersCloudflareTokensOperationSubscribe RelayTokenNewResponseIssuersCloudflareTokensOperation = "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 RelayTokenNewResponseIssuersIssuer` - `const RelayTokenNewResponseIssuersIssuerCloudflare RelayTokenNewResponseIssuersIssuer = "cloudflare"` - `Type RelayTokenNewResponseIssuersType` - `const RelayTokenNewResponseIssuersTypeCloudflareJWT RelayTokenNewResponseIssuersType = "cloudflare_jwt"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) token, err := client.MoQ.Relays.Tokens.New( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", moq.RelayTokenNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Operations: cloudflare.F([]moq.RelayTokenNewParamsOperation{moq.RelayTokenNewParamsOperationPublish, moq.RelayTokenNewParamsOperationSubscribe}), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, relayID, query) (*RelayTokenListResponse, error)` **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 - `relayID string` - `query RelayTokenListParams` - `AccountID param.Field[string]` Cloudflare account identifier. ### Returns - `type RelayTokenListResponse struct{…}` 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 []RelayTokenListResponseIssuer` - `CloudflareTokens []RelayTokenListResponseIssuersCloudflareToken` Always present ([] when empty). - `Created Time` - `Expires Time` Mandatory; no more than 1 year after `created`. - `Jti string` Token identity and registry key (32 hex chars). - `Operations []RelayTokenListResponseIssuersCloudflareTokensOperation` 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. - `const RelayTokenListResponseIssuersCloudflareTokensOperationPublish RelayTokenListResponseIssuersCloudflareTokensOperation = "publish"` - `const RelayTokenListResponseIssuersCloudflareTokensOperationSubscribe RelayTokenListResponseIssuersCloudflareTokensOperation = "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 RelayTokenListResponseIssuersIssuer` - `const RelayTokenListResponseIssuersIssuerCloudflare RelayTokenListResponseIssuersIssuer = "cloudflare"` - `Type RelayTokenListResponseIssuersType` - `const RelayTokenListResponseIssuersTypeCloudflareJWT RelayTokenListResponseIssuersType = "cloudflare_jwt"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) tokens, err := client.MoQ.Relays.Tokens.List( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", moq.RelayTokenListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, relayID, jti, body) (*RelayTokenDeleteResponse, error)` **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 - `relayID string` - `jti string` - `body RelayTokenDeleteParams` - `AccountID param.Field[string]` Cloudflare account identifier. ### Returns - `type RelayTokenDeleteResponse struct{…}` - `Errors []RelayTokenDeleteResponseError` - `Code int64` - `Message string` - `Messages []RelayTokenDeleteResponseMessage` - `Code int64` - `Message string` - `Success bool` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/moq" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) token, err := client.MoQ.Relays.Tokens.Delete( context.TODO(), "a1b2c3d4e5f67890a1b2c3d4e5f67890", "f3a1b2c3d4e5f67890a1b2c3d4e5f678", moq.RelayTokenDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", token.Errors) } ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true } ```