Skip to main content
Logo
Explore APIsContact Us
  • Home
  1. Resources
  3. Virtual Stadium
  5. API Endpoints

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

EnvironmentBase URLPurpose
Management APIhttps://management.vs.sportradar.com/apiChannel and user management
Moderation APIhttps://moderation.vs.sportradar.com/apiContent 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

NameTypeAttributesDescription
channelIdstring<required>The unique identifier assigned to each channel. Maximum length is 128 characters. Valid values: alphanumeric characters and punctuation: (!"#$%&'()*+,-./:;<=>?@[\]^_'{|}~)
channelNamestring<required>The channel name displayed in the header and tags.
expirationDatetimeinteger<required>Expiration date as Unix timestamp. Must be set to future datetime.
metadataObject<required>Metadata object in any form.
moderationSourceEnum<required>Valid values: VS, EXTERNAL.
relatedCompetitionsArray.<ChannelRelatedCompetitionRequest>Array of related competitions. See below.
parentIdstringParent channel ID for hierarchical organization.
receiveEventsFromChildrenbooleanWhether this channel should receive events from child channels.
channelTypeEnumValid values: MATCH, TOURNAMENT.
testChannelbooleanMark channel as test channel for development purposes.
highPrioritybooleanCan be set to true only if moderationSource is set to VS.

#Related Competition Structure

NameTypeAttributesDescription
eventTypesArray.<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)
srEntityIdstringSportradar match, tournament or category id. Format: "sr:match:57969543". See Getting Identifiers for details on obtaining these IDs.
clientCompetitionIdstringYour internal competition identifier for mapping purposes. Used alongside srEntityId for ID mapping.

#Example Request

json
{
    "channelId": "spain-germany-2024",
    "channelName": "Spain vs Germany - UEFA Championship",
    "expirationDatetime": 1940753098,
    "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"
}

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

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

#Authentication

  • Header: Authorization: Bearer <jwt-token>

#Path Parameters

ParameterTypeDescription
channelIdstringThe 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

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

#Authentication

  • Header: Authorization: Bearer <jwt-token>

#Path Parameters

ParameterTypeDescription
channelIdstringThe 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

ParameterTypeDescription
channelIdstringThe 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

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

Status CodeDescriptionCommon Causes
400 Bad RequestInvalid request parametersMissing required fields, invalid data format, validation errors
401 UnauthorizedAuthentication requiredMissing or invalid JWT token
403 ForbiddenInsufficient permissionsUser role doesn't have required permissions
404 Not FoundResource not foundChannel doesn't exist, invalid channel ID
409 ConflictResource conflictDuplicate channel ID, concurrent modification
422 Unprocessable EntityValidation errorInvalid field values, business rule violations
429 Too Many RequestsRate limit exceededToo many requests in time window
500 Internal Server ErrorServer errorSystem 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 →

#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
Last updated about 1 month ago
Is this site helpful?
Virtual Stadium, Moderation, Engagement Tools
API AuthenticationWeb
On this page
  • Base URLs
  • Channel Management Endpoints
  • Create Channel
  • Create Channels in Batch
  • Update Channel
  • Delete Channel
  • Clear Channel Messages
  • Additional Endpoints (External Services)
  • External Moderation Service Endpoints
  • Error Responses
  • Common HTTP Status Codes
  • Error Response Format
  • Best Practices
  • Interactive Documentation
  • Support