API Endpoints

API Endpoints | Virtual Stadium | API Hub

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 for setup instructions.

#Channel Management Endpoints

#Create Channel

Create a new chat channel for events, tournaments, or ongoing discussions.

#Endpoint

text

POST https://management.vs.sportradar.com/api/channel/create

#Authentication

Header: Authorization: Bearer <jwt-token>

#Request Body

#Example Request

json

{
    "channelId": "spain-germany-2024",
    "channelName": "Spain vs Germany - UEFA Championship",
    "expirationDatetime": 1940753098,
    "permanentChannel": false,
    "relatedCompetitions": [{
        "srEntityId": "sr:match:57969543",
        "

Example Request with Permanent Channel:

json

{
    "channelId": "league-discussion",
    "channelName": "League Discussion Channel",
    "permanentChannel": true,
    "permanentChannelMessageExpirationDays": 90,
    "relatedCompetitions": [{
        "srEntityId": "sr:category:123456",
        "

#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

text

POST https://management.vs.sportradar.com/api/channel/create/batch

#Authentication

Header: Authorization: Bearer <jwt-token>

#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"

#Response

Success (201 Created):

json

{
    "success": true,
    "message": "2 channels created successfully",
    "created": [
        {
            "channelId": "match-1-semifinals",
            "status": "created"
        },
        {
            "channelId": "match-2-semifinals", 
            "status"

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

text

PUT https://management.vs.sportradar.com/api/channel/{channelId}

#Authentication

Header: Authorization: Bearer <jwt-token>

#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"

#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

text

DELETE https://management.vs.sportradar.com/api/channel/{channelId}

#Authentication

Header: Authorization: Bearer <jwt-token>

#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

text

DELETE https://management.vs.sportradar.com/api/channel/{channelId}/clear

#Authentication

Header: Authorization: Bearer <jwt-token>

#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"
}

#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

text

POST https://moderator.vs.sportradar.com/api/operator/{operatorId}/channel/create

#Update MaaS Channel

text

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

#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

#Interactive Documentation

For complete API documentation with interactive examples and testing capabilities:

Swagger UI Documentation →

#Support

For endpoint-specific questions or technical support:

API Documentation: Interactive Swagger UI
Authentication Setup: JWT Tutorial
Integration Support: Contact the Virtual Stadium development team

Name	Type	Attributes	Description
`channelId`	string	`<required>`	The unique identifier assigned to each channel. Maximum length is 128 characters. Valid values: alphanumeric characters and punctuation: `(!"#$%&'()*+,-./:;<=>?@[\]^_'{\|}~)`
`channelName`	string	`<required>`	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	`<required>`	Metadata object in any form.
`moderationSource`	Enum	`<required>`	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.`<ChannelRelatedCompetitionRequest>`		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`.

Name	Type	Attributes	Description
`eventTypes`	Array.`<Enum>`	`<required>`	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 for details on obtaining these IDs.
`clientCompetitionId`	string		Your internal competition identifier for mapping purposes. Used alongside `srEntityId` for ID mapping.

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

API Endpoints

#Base URLs

Expanded Table

#Channel Management Endpoints

#Create Channel

#Endpoint

#Authentication

#Request Body

Expanded Table

#Related Competition Structure

Expanded Table

#Example Request

#Response

#Create Channels in Batch

#Endpoint

#Authentication

#Request Body

#Example Request

#Response

#Update Channel

#Endpoint

#Authentication

#Path Parameters

Expanded Table

#Request Body

#Example Request

#Response

#Delete Channel

#Endpoint

#Authentication

#Path Parameters

Expanded Table

#Response

#Clear Channel Messages

#Endpoint

#Authentication

#Path Parameters

Expanded Table

#Response

#Additional Endpoints (External Services)

#External Moderation Service Endpoints

#Create MaaS Channel

#Update MaaS Channel

#Error Responses

#Common HTTP Status Codes

Expanded Table

#Error Response Format

#Best Practices

#Interactive Documentation

#Support