--- title: "API Endpoints" canonical_url: "https://apidocs.sportradar.com/resources/virtual-stadium/docs/api/endpoints" markdown_url: "https://apidocs.sportradar.com/resources/virtual-stadium/docs/api/endpoints.md" last_updated: "2026-06-02T10:52:14Z" --- # API Endpoints This section provides detailed documentation for all Virtual Stadium API endpoints. Each endpoint includes request/response specifications, authentication requirements, and practical examples. ## Base URLs | Environment | Base URL | Purpose | | ------------------ | ------------------------------------------ | ----------------------------- | | **Management API** | `https://management.vs.sportradar.com/api` | Channel and user management | | **Moderation API** | `https://moderation.vs.sportradar.com/api` | Content moderation operations | > **Authentication Required** > > All endpoints require JWT authentication with appropriate user roles. See [Authentication Guide](https://apidocs.sportradar.com/resources/virtual-stadium/docs/api/authentication.md) for setup instructions. *** ## Channel Management Endpoints ### Create Channel Create a new chat channel for events, tournaments, or ongoing discussions. #### Endpoint ``` POST https://management.vs.sportradar.com/api/channel/create ``` #### Authentication - **Header**: `Authorization: Bearer ` #### Request Body | Name | Type | Attributes | Description | | --------------------------------------- | ---------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `channelId` | **string** | `` | The unique identifier assigned to each channel. Maximum length is 128 characters. Valid values: alphanumeric characters and punctuation: `(!"#$%&'()*+,-./:;<=>?@[\]^_'{\|}~)` | | `channelName` | **string** | `` | The channel name displayed in the header and tags. | | `expirationDatetime` | **integer** | | Expiration date as Unix timestamp. Must be set to future datetime. Required unless `permanentChannel` is set to `true`. | | `metadata` | **Object** | `` | Metadata object in any form. | | `moderationSource` | **Enum** | `` | Valid values: `VS`, `EXTERNAL`. | | `permanentChannel` | **boolean** | | If set to `true`, the channel will never expire and `expirationDatetime` is not required. Default is `false`. | | `permanentChannelMessageExpirationDays` | **number** | | Number of days after which messages are automatically deleted from the channel. Only applicable when `permanentChannel` is `true`. If not set, default is 1 day. | | `relatedCompetitions` | **Array.``** | | Array of related competitions. See below. | | `parentId` | **string** | | Parent channel ID for hierarchical organization. | | `receiveEventsFromChildren` | **boolean** | | Whether this channel should receive events from child channels. | | `channelType` | **Enum** | | Valid values: `MATCH`, `TOURNAMENT`. | | `testChannel` | **boolean** | | Mark channel as test channel for development purposes. | | `highPriority` | **boolean** | | Can be set to `true` only if `moderationSource` is set to `VS`. | #### Related Competition Structure | Name | Type | Attributes | Description | | --------------------- | ------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eventTypes` | **Array.``** | `` | List of event types that will trigger event messages in the channel. (Valid values: `GOAL`, `YELLOW_CARD`, `RED_CARD`, `CORNER`, `PENALTY_KICK`, `PENALTY_SHOOTOUT`, `THROW_IN`, `SHOT_ON_TARGET`, `OFFSIDE`, `SECOND_HALF_STARTED`, `OVERTIME_STARTED`, `PENALTY_SHOOTOUT_STARTED`, `ONE_POINT_SCORED`, `TWO_POINT_SCORED`, `THREE_POINT_SCORED`, `TIMEOUT`, `PLAYER_EJECTED`, `QUARTER_STARTED`, `GAME_WON`, `BREAK_WON`, `SET_WON`, `SET_STARTED`, `MATCH_STARTED`, `MATCH_ENDED`, `TOURNAMENT_MATCH_START_IN_ONE_DAY`, `TOURNAMENT_MATCH_START_IN_ONE_HOUR`, `TOURNAMENT_MATCH_START_IN_FIVE_MINUTES`) | | `srEntityId` | **string** | | Sportradar match, tournament or category id. Format: `"sr:match:57969543"`. See [Getting Identifiers](https://apidocs.sportradar.com/resources/virtual-stadium/docs/widgets/tutorials/getting-identifiers.md) for details on obtaining these IDs. | | `clientCompetitionId` | **string** | | Your internal competition identifier for mapping purposes. Used alongside `srEntityId` for [ID mapping](https://apidocs.sportradar.com/resources/virtual-stadium/docs/widgets/tutorials/getting-identifiers.md). | #### Example Request ```json { "channelId": "spain-germany-2024", "channelName": "Spain vs Germany - UEFA Championship", "expirationDatetime": 1940753098, "permanentChannel": false, "relatedCompetitions": [{ "srEntityId": "sr:match:57969543", "clientCompetitionId": "2016", "eventTypes": ["GOAL", "YELLOW_CARD", "RED_CARD", "CORNER", "PENALTY_KICK", "PENALTY_SHOOTOUT"] }], "receiveEventsFromChildren": true, "metadata": { "sport": "football", "league": "UEFA" }, "channelType": "MATCH", "testChannel": false, "highPriority": true, "moderationSource": "VS" } ``` **Example Request with Permanent Channel:** ```json { "channelId": "league-discussion", "channelName": "League Discussion Channel", "permanentChannel": true, "permanentChannelMessageExpirationDays": 90, "relatedCompetitions": [{ "srEntityId": "sr:category:123456", "clientCompetitionId": "league-2024", "eventTypes": ["GOAL", "YELLOW_CARD", "RED_CARD"] }], "receiveEventsFromChildren": true, "metadata": { "sport": "football", "league": "Premier League" }, "channelType": "TOURNAMENT", "testChannel": false, "highPriority": false, "moderationSource": "VS", "expirationDatetime": null } ``` #### Response **Success (201 Created):** ```json { "success": true, "channelId": "spain-germany-2024", "message": "Channel created successfully" } ``` **Error (400 Bad Request):** ```json { "success": false, "error": "Invalid channel configuration", "details": "channelId must be unique" } ``` *** ### Create Channels in Batch Create multiple channels simultaneously for improved efficiency. #### Endpoint ``` POST https://management.vs.sportradar.com/api/channel/create/batch ``` #### Authentication - **Header**: `Authorization: Bearer ` #### Request Body Array of channel objects using the same structure as single channel creation. #### Example Request ```json [ { "channelId": "match-1-semifinals", "channelName": "Semifinals Match 1", "expirationDatetime": 1940753098, "relatedCompetitions": [{ "srEntityId": "sr:match:57969543", "clientCompetitionId": "2016", "eventTypes": ["GOAL", "YELLOW_CARD", "RED_CARD"] }], "receiveEventsFromChildren": true, "metadata": {}, "channelType": "MATCH", "testChannel": false, "highPriority": false, "moderationSource": "VS" }, { "channelId": "match-2-semifinals", "channelName": "Semifinals Match 2", "expirationDatetime": 1940753098, "relatedCompetitions": [{ "srEntityId": "sr:match:57969544", "clientCompetitionId": "2017", "eventTypes": ["GOAL", "YELLOW_CARD", "RED_CARD"] }], "receiveEventsFromChildren": true, "metadata": {}, "channelType": "MATCH", "testChannel": false, "highPriority": false, "moderationSource": "VS" } ] ``` #### Response **Success (201 Created):** ```json { "success": true, "message": "2 channels created successfully", "created": [ { "channelId": "match-1-semifinals", "status": "created" }, { "channelId": "match-2-semifinals", "status": "created" } ], "failed": [] } ``` > **Batch Operations** > > Bulk channel creation uses the same structure as single channel creation but with an array of channel objects in the request body. This is more efficient for creating multiple channels simultaneously. *** ### Update Channel Update an existing channel's configuration. Based on the #codebase, all metadata except the channel ID can be modified. #### Endpoint ``` PUT https://management.vs.sportradar.com/api/channel/{channelId} ``` #### Authentication - **Header**: `Authorization: Bearer ` #### Path Parameters | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------------- | | `channelId` | string | The unique identifier of the channel to update | #### Request Body Same structure as channel creation, but `channelId` cannot be modified. #### Example Request ```json { "channelName": "Spain vs Germany - UPDATED NAME", "expirationDatetime": 1940853098, "metadata": { "sport": "football", "league": "UEFA", "updated": true }, "highPriority": false, "moderationSource": "VS" } ``` #### Response **Success (200 OK):** ```json { "success": true, "channelId": "spain-germany-2024", "message": "Channel updated successfully" } ``` **Error (404 Not Found):** ```json { "success": false, "error": "Channel not found", "details": "Channel with ID 'spain-germany-2024' does not exist" } ``` > **Important** > > The channel ID cannot be modified after creation. All other metadata can be updated as needed. *** ### Delete Channel Permanently delete a channel and all associated data. #### Endpoint ``` DELETE https://management.vs.sportradar.com/api/channel/{channelId} ``` #### Authentication - **Header**: `Authorization: Bearer ` #### Path Parameters | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------------- | | `channelId` | string | The unique identifier of the channel to delete | #### Response **Success (200 OK):** ```json { "success": true, "channelId": "spain-germany-2024", "message": "Channel deleted successfully" } ``` **Error (404 Not Found):** ```json { "success": false, "error": "Channel not found", "details": "Channel with ID 'spain-germany-2024' does not exist" } ``` **Error (403 Forbidden):** ```json { "success": false, "error": "Insufficient permissions", "details": "SUPERVISOR role required for channel deletion" } ``` > **Destructive Operation** > > Channel deletion is permanent and cannot be undone. All messages, user data, and channel history will be permanently removed. *** ### Clear Channel Messages Delete all messages from a channel while keeping the channel active. #### Endpoint ``` DELETE https://management.vs.sportradar.com/api/channel/{channelId}/clear ``` #### Authentication - **Header**: `Authorization: Bearer ` #### Path Parameters | Parameter | Type | Description | | ----------- | ------ | --------------------------------------------- | | `channelId` | string | The unique identifier of the channel to clear | #### Response **Success (200 OK):** ```json { "success": true, "channelId": "spain-germany-2024", "message": "Channel messages cleared successfully", "messagesDeleted": 1247 } ``` **Error (404 Not Found):** ```json { "success": false, "error": "Channel not found", "details": "Channel with ID 'spain-germany-2024' does not exist" } ``` > **Use Case** > > This endpoint is useful for cleaning chat history while maintaining the channel for continued use, particularly helpful for persistent channels or when starting fresh content. *** ## Additional Endpoints (External Services) Based on the #codebase, there are additional endpoints for external moderation services: ### External Moderation Service Endpoints For channels using **Moderation as a Service (MaaS)**, different base URLs are used: #### Create MaaS Channel ``` POST https://moderator.vs.sportradar.com/api/operator/{operatorId}/channel/create ``` #### Update MaaS Channel ``` PUT https://moderator.vs.sportradar.com/api/operator/{operatorId}/channel/{channelId}/update ``` **Requirements:** - The `moderationSource` parameter must be set to `"EXTERNAL"` - Operator ID must be provided in the path - High priority cannot be enabled for external moderation channels *** ## Error Responses ### Common HTTP Status Codes | Status Code | Description | Common Causes | | ----------------------------- | -------------------------- | --------------------------------------------------------------- | | **400 Bad Request** | Invalid request parameters | Missing required fields, invalid data format, validation errors | | **401 Unauthorized** | Authentication required | Missing or invalid JWT token | | **403 Forbidden** | Insufficient permissions | User role doesn't have required permissions | | **404 Not Found** | Resource not found | Channel doesn't exist, invalid channel ID | | **409 Conflict** | Resource conflict | Duplicate channel ID, concurrent modification | | **422 Unprocessable Entity** | Validation error | Invalid field values, business rule violations | | **429 Too Many Requests** | Rate limit exceeded | Too many requests in time window | | **500 Internal Server Error** | Server error | System error, contact support | ### Error Response Format All error responses follow this standard format: ```json { "success": false, "error": "Error category description", "details": "Specific error details", "code": "ERROR_CODE" } ``` ## Best Practices > **Channel Management Best Practices** > > - **Use descriptive `channelId` values** for easier identification and debugging > - **Set appropriate `expirationDatetime`** based on event duration (consider overtime, delays) > - **Only enable `highPriority`** for truly critical channels to maintain system performance > - **Test configurations** using `testChannel: true` before production deployment > - **Use batch creation** when creating multiple channels to improve efficiency > - **Implement proper error handling** for all endpoint calls > - **Monitor rate limits** and implement backoff strategies ## Interactive Documentation For complete API documentation with interactive examples and testing capabilities: **[Swagger UI Documentation →](https://management.vs.sportradar.com/apidocs/swagger-ui/index.html?urls.primaryName=public)** ## Support For endpoint-specific questions or technical support: - **API Documentation**: [Interactive Swagger UI](https://management.vs.sportradar.com/apidocs/swagger-ui/index.html?urls.primaryName=public) - **Authentication Setup**: [JWT Tutorial](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/jwt.md) - **Integration Support**: Contact the Virtual Stadium development team