'2.0', 'service' => '

Introduction

The Amazon Interactive Video Service (IVS) stage API is REST compatible, using a standard HTTP API and an AWS EventBridge event stream for responses. JSON is used for both requests and responses, including errors.

Terminology:

The IVS stage API sometimes is referred to as the IVS RealTime API.
A participant token is an authorization token used to publish/subscribe to a stage.
A participant object represents participants (people) in the stage and contains information about them. When a token is created, it includes a participant ID; when a participant uses that token to join a stage, the participant is associated with that participant ID There is a 1:1 mapping between participant tokens and participants.

Resources

The following resources contain information about your IVS live stream (see Getting Started with Amazon IVS):

Stage — A stage is a virtual space where multiple participants can exchange audio and video in real time.

Tagging

A tag is a metadata label that you assign to an AWS resource. A tag comprises a key and a value, both set by you. For example, you might set a tag as topic:nature to label a particular video category. See Tagging AWS Resources for more information, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS stages has no service-specific constraints beyond what is documented there.

Tags can help you identify and organize your AWS resources. For example, you can use the same tag for different resources to indicate that they are related. You can also use tags to manage access (see Access Tags).

The Amazon IVS stage API has these tag-related endpoints: TagResource, UntagResource, and ListTagsForResource. The following resource supports tagging: Stage.

At most 50 tags can be applied to a resource.

Stages Endpoints

CreateParticipantToken — Creates an additional token for a specified stage. This can be done after stage creation or when tokens expire.
CreateStage — Creates a new stage (and optionally participant tokens).
DeleteStage — Shuts down and deletes the specified stage (disconnecting all participants).
DisconnectParticipant — Disconnects a specified participant and revokes the participant permanently from a specified stage.
GetParticipant — Gets information about the specified participant token.
GetStage — Gets information for the specified stage.
GetStageSession — Gets information for the specified stage session.
ListParticipantEvents — Lists events for a specified participant that occurred during a specified stage session.
ListParticipants — Lists all participants in a specified stage session.
ListStages — Gets summary information about all stages in your account, in the AWS region where the API request is processed.
ListStageSessions — Gets all sessions for a specified stage.
UpdateStage — Updates a stage’s configuration.

Tags Endpoints

ListTagsForResource — Gets information about AWS tags for the specified ARN.
TagResource — Adds or updates tags for the AWS resource with the specified ARN.
UntagResource — Removes tags from the resource with the specified ARN.

', 'operations' => [ 'CreateParticipantToken' => '

Creates an additional token for a specified stage. This can be done after stage creation or when tokens expire. Tokens always are scoped to the stage for which they are created.

Encryption keys are owned by Amazon IVS and never used directly by your application.

', 'CreateStage' => '

Creates a new stage (and optionally participant tokens).

', 'DeleteStage' => '

Shuts down and deletes the specified stage (disconnecting all participants).

', 'DisconnectParticipant' => '

Disconnects a specified participant and revokes the participant permanently from a specified stage.

', 'GetParticipant' => '

Gets information about the specified participant token.

', 'GetStage' => '

Gets information for the specified stage.

', 'GetStageSession' => '

Gets information for the specified stage session.

', 'ListParticipantEvents' => '

Lists events for a specified participant that occurred during a specified stage session.

', 'ListParticipants' => '

Lists all participants in a specified stage session.

', 'ListStageSessions' => '

Gets all sessions for a specified stage.

', 'ListStages' => '

Gets summary information about all stages in your account, in the AWS region where the API request is processed.

', 'ListTagsForResource' => '

Gets information about AWS tags for the specified ARN.

', 'TagResource' => '

Adds or updates tags for the AWS resource with the specified ARN.

', 'UntagResource' => '

Removes tags from the resource with the specified ARN.

', 'UpdateStage' => '

Updates a stage’s configuration.

', ], 'shapes' => [ 'AccessDeniedException' => [ 'base' => '

', 'refs' => [], ], 'ConflictException' => [ 'base' => '

', 'refs' => [], ], 'CreateParticipantTokenRequest' => [ 'base' => NULL, 'refs' => [], ], 'CreateParticipantTokenResponse' => [ 'base' => NULL, 'refs' => [], ], 'CreateStageRequest' => [ 'base' => NULL, 'refs' => [], ], 'CreateStageResponse' => [ 'base' => NULL, 'refs' => [], ], 'DeleteStageRequest' => [ 'base' => NULL, 'refs' => [], ], 'DeleteStageResponse' => [ 'base' => NULL, 'refs' => [], ], 'DisconnectParticipantReason' => [ 'base' => NULL, 'refs' => [ 'DisconnectParticipantRequest$reason' => '

Description of why this participant is being disconnected.

', ], ], 'DisconnectParticipantRequest' => [ 'base' => NULL, 'refs' => [], ], 'DisconnectParticipantResponse' => [ 'base' => NULL, 'refs' => [], ], 'Event' => [ 'base' => '

An occurrence during a stage session.

', 'refs' => [ 'EventList$member' => NULL, ], ], 'EventErrorCode' => [ 'base' => NULL, 'refs' => [ 'Event$errorCode' => '

If the event is an error event, the error code is provided to give insight into the specific error that occurred. If the event is not an error event, this field is null. INSUFFICIENT_CAPABILITIES indicates that the participant tried to take an action that the participant’s token is not allowed to do. For more information about participant capabilities, see the capabilities field in CreateParticipantToken.

', ], ], 'EventList' => [ 'base' => NULL, 'refs' => [ 'ListParticipantEventsResponse$events' => '

List of the matching events.

', ], ], 'EventName' => [ 'base' => NULL, 'refs' => [ 'Event$name' => '

The name of the event.

', ], ], 'GetParticipantRequest' => [ 'base' => NULL, 'refs' => [], ], 'GetParticipantResponse' => [ 'base' => NULL, 'refs' => [], ], 'GetStageRequest' => [ 'base' => NULL, 'refs' => [], ], 'GetStageResponse' => [ 'base' => NULL, 'refs' => [], ], 'GetStageSessionRequest' => [ 'base' => NULL, 'refs' => [], ], 'GetStageSessionResponse' => [ 'base' => NULL, 'refs' => [], ], 'InternalServerException' => [ 'base' => '

', 'refs' => [], ], 'ListParticipantEventsRequest' => [ 'base' => NULL, 'refs' => [], ], 'ListParticipantEventsResponse' => [ 'base' => NULL, 'refs' => [], ], 'ListParticipantsRequest' => [ 'base' => NULL, 'refs' => [], ], 'ListParticipantsResponse' => [ 'base' => NULL, 'refs' => [], ], 'ListStageSessionsRequest' => [ 'base' => NULL, 'refs' => [], ], 'ListStageSessionsResponse' => [ 'base' => NULL, 'refs' => [], ], 'ListStagesRequest' => [ 'base' => NULL, 'refs' => [], ], 'ListStagesResponse' => [ 'base' => NULL, 'refs' => [], ], 'ListTagsForResourceRequest' => [ 'base' => NULL, 'refs' => [], ], 'ListTagsForResourceResponse' => [ 'base' => NULL, 'refs' => [], ], 'MaxParticipantEventResults' => [ 'base' => NULL, 'refs' => [ 'ListParticipantEventsRequest$maxResults' => '

Maximum number of results to return. Default: 50.

', ], ], 'MaxParticipantResults' => [ 'base' => NULL, 'refs' => [ 'ListParticipantsRequest$maxResults' => '

Maximum number of results to return. Default: 50.

', ], ], 'MaxStageResults' => [ 'base' => NULL, 'refs' => [ 'ListStagesRequest$maxResults' => '

Maximum number of results to return. Default: 50.

', ], ], 'MaxStageSessionResults' => [ 'base' => NULL, 'refs' => [ 'ListStageSessionsRequest$maxResults' => '

Maximum number of results to return. Default: 50.

', ], ], 'PaginationToken' => [ 'base' => NULL, 'refs' => [ 'ListParticipantEventsRequest$nextToken' => '

The first participant to retrieve. This is used for pagination; see the nextToken response field.

', 'ListParticipantEventsResponse$nextToken' => '

If there are more rooms than maxResults, use nextToken in the request to get the next set.

', 'ListParticipantsRequest$nextToken' => '

The first participant to retrieve. This is used for pagination; see the nextToken response field.

', 'ListParticipantsResponse$nextToken' => '

If there are more rooms than maxResults, use nextToken in the request to get the next set.

', 'ListStageSessionsRequest$nextToken' => '

The first stage to retrieve. This is used for pagination; see the nextToken response field.

', 'ListStageSessionsResponse$nextToken' => '

If there are more rooms than maxResults, use nextToken in the request to get the next set.

', 'ListStagesRequest$nextToken' => '

The first stage to retrieve. This is used for pagination; see the nextToken response field.

', 'ListStagesResponse$nextToken' => '

If there are more rooms than maxResults, use nextToken in the request to get the next set.

', ], ], 'Participant' => [ 'base' => '

Object describing a participant that has joined a stage.

', 'refs' => [ 'GetParticipantResponse$participant' => '

The participant that is returned.

', ], ], 'ParticipantAttributes' => [ 'base' => NULL, 'refs' => [ 'Participant$attributes' => '

Application-provided attributes to encode into the token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

', ], ], 'ParticipantId' => [ 'base' => NULL, 'refs' => [ 'Event$participantId' => '

Unique identifier for the participant who triggered the event. This is assigned by IVS.

', 'Event$remoteParticipantId' => '

Unique identifier for the remote participant. For a subscribe event, this is the publisher. For a publish or join event, this is null. This is assigned by IVS.

', 'GetParticipantRequest$participantId' => '

Unique identifier for the participant. This is assigned by IVS and returned by CreateParticipantToken.

', 'ListParticipantEventsRequest$participantId' => '

Unique identifier for this participant. This is assigned by IVS and returned by CreateParticipantToken.

', 'Participant$participantId' => '

Unique identifier for this participant, assigned by IVS.

', 'ParticipantSummary$participantId' => '

Unique identifier for this participant, assigned by IVS.

', ], ], 'ParticipantList' => [ 'base' => NULL, 'refs' => [ 'ListParticipantsResponse$participants' => '

List of the matching participants (summary information only).

', ], ], 'ParticipantState' => [ 'base' => NULL, 'refs' => [ 'ListParticipantsRequest$filterByState' => '

Filters the response list to only show participants in the specified state. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request.

', 'Participant$state' => '

Whether the participant is connected to or disconnected from the stage.

', 'ParticipantSummary$state' => '

Whether the participant is connected to or disconnected from the stage.

', ], ], 'ParticipantSummary' => [ 'base' => '

Summary object describing a participant that has joined a stage.

', 'refs' => [ 'ParticipantList$member' => NULL, ], ], 'ParticipantToken' => [ 'base' => '

Object specifying a participant token in a stage.

', 'refs' => [ 'CreateParticipantTokenResponse$participantToken' => '

The participant token that was created.

', 'ParticipantTokenList$member' => NULL, ], ], 'ParticipantTokenAttributes' => [ 'base' => NULL, 'refs' => [ 'CreateParticipantTokenRequest$attributes' => '

', 'ParticipantToken$attributes' => '

Application-provided attributes to encode into the token and attach to a stage. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

', 'ParticipantTokenConfiguration$attributes' => '

Application-provided attributes to encode into the corresponding participant token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

', ], ], 'ParticipantTokenCapabilities' => [ 'base' => NULL, 'refs' => [ 'CreateParticipantTokenRequest$capabilities' => '

Set of capabilities that the user is allowed to perform in the stage. Default: PUBLISH, SUBSCRIBE.

', 'ParticipantToken$capabilities' => '

Set of capabilities that the user is allowed to perform in the stage.

', 'ParticipantTokenConfiguration$capabilities' => '

Set of capabilities that the user is allowed to perform in the stage.

', ], ], 'ParticipantTokenCapability' => [ 'base' => NULL, 'refs' => [ 'ParticipantTokenCapabilities$member' => NULL, ], ], 'ParticipantTokenConfiguration' => [ 'base' => '

Object specifying a participant token configuration in a stage.

', 'refs' => [ 'ParticipantTokenConfigurations$member' => NULL, ], ], 'ParticipantTokenConfigurations' => [ 'base' => NULL, 'refs' => [ 'CreateStageRequest$participantTokenConfigurations' => '

Array of participant token configuration objects to attach to the new stage.

', ], ], 'ParticipantTokenDurationMinutes' => [ 'base' => NULL, 'refs' => [ 'CreateParticipantTokenRequest$duration' => '

Duration (in minutes), after which the token expires. Default: 720 (12 hours).

', 'ParticipantToken$duration' => '

Duration (in minutes), after which the participant token expires. Default: 720 (12 hours).

', 'ParticipantTokenConfiguration$duration' => '

Duration (in minutes), after which the corresponding participant token expires. Default: 720 (12 hours).

', ], ], 'ParticipantTokenExpirationTime' => [ 'base' => NULL, 'refs' => [ 'ParticipantToken$expirationTime' => '

ISO 8601 timestamp (returned as a string) for when this token expires.

', ], ], 'ParticipantTokenId' => [ 'base' => NULL, 'refs' => [ 'DisconnectParticipantRequest$participantId' => '

Identifier of the participant to be disconnected. This is assigned by IVS and returned by CreateParticipantToken.

', 'ParticipantToken$participantId' => '

Unique identifier for this participant token, assigned by IVS.

', ], ], 'ParticipantTokenList' => [ 'base' => NULL, 'refs' => [ 'CreateStageResponse$participantTokens' => '

Participant tokens attached to the stage. These correspond to the participants in the request.

', ], ], 'ParticipantTokenString' => [ 'base' => NULL, 'refs' => [ 'ParticipantToken$token' => '

The issued client token, encrypted.

', ], ], 'ParticipantTokenUserId' => [ 'base' => NULL, 'refs' => [ 'CreateParticipantTokenRequest$userId' => '

Name that can be specified to help identify the token. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

', 'ParticipantToken$userId' => '

Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

', 'ParticipantTokenConfiguration$userId' => '

', ], ], 'PendingVerification' => [ 'base' => '

', 'refs' => [], ], 'Published' => [ 'base' => NULL, 'refs' => [ 'ListParticipantsRequest$filterByPublished' => '

Filters the response list to only show participants who published during the stage session. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request.

', 'Participant$published' => '

Whether the participant ever published to the stage session.

', 'ParticipantSummary$published' => '

Whether the participant ever published to the stage session.

', ], ], 'ResourceArn' => [ 'base' => NULL, 'refs' => [ 'ListTagsForResourceRequest$resourceArn' => '

The ARN of the resource to be retrieved. The ARN must be URL-encoded.

', 'TagResourceRequest$resourceArn' => '

The ARN of the resource to be tagged. The ARN must be URL-encoded.

', 'UntagResourceRequest$resourceArn' => '

The ARN of the resource to be untagged. The ARN must be URL-encoded.

', ], ], 'ResourceNotFoundException' => [ 'base' => '

', 'refs' => [], ], 'ServiceQuotaExceededException' => [ 'base' => '

', 'refs' => [], ], 'Stage' => [ 'base' => '

Object specifying a stage.

', 'refs' => [ 'CreateStageResponse$stage' => '

The stage that was created.

', 'GetStageResponse$stage' => '

The stage that is returned.

', 'UpdateStageResponse$stage' => '

The updated stage.

', ], ], 'StageArn' => [ 'base' => NULL, 'refs' => [ 'CreateParticipantTokenRequest$stageArn' => '

ARN of the stage to which this token is scoped.

', 'DeleteStageRequest$arn' => '

ARN of the stage to be deleted.

', 'DisconnectParticipantRequest$stageArn' => '

ARN of the stage to which the participant is attached.

', 'GetParticipantRequest$stageArn' => '

Stage ARN.

', 'GetStageRequest$arn' => '

ARN of the stage for which the information is to be retrieved.

', 'GetStageSessionRequest$stageArn' => '

ARN of the stage for which the information is to be retrieved.

', 'ListParticipantEventsRequest$stageArn' => '

Stage ARN.

', 'ListParticipantsRequest$stageArn' => '

Stage ARN.

', 'ListStageSessionsRequest$stageArn' => '

Stage ARN.

', 'Stage$arn' => '

Stage ARN.

', 'StageSummary$arn' => '

Stage ARN.

', 'UpdateStageRequest$arn' => '

ARN of the stage to be updated.

', ], ], 'StageName' => [ 'base' => NULL, 'refs' => [ 'CreateStageRequest$name' => '

Optional name that can be specified for the stage being created.

', 'Stage$name' => '

Stage name.

', 'StageSummary$name' => '

Stage name.

', 'UpdateStageRequest$name' => '

Name of the stage to be updated.

', ], ], 'StageSession' => [ 'base' => '

A stage session begins when the first participant joins a stage and ends after the last participant leaves the stage. A stage session helps with debugging stages by grouping events and participants into shorter periods of time (i.e., a session), which is helpful when stages are used over long periods of time.

', 'refs' => [ 'GetStageSessionResponse$stageSession' => '

The stage session that is returned.

', ], ], 'StageSessionId' => [ 'base' => NULL, 'refs' => [ 'GetParticipantRequest$sessionId' => '

ID of a session within the stage.

', 'GetStageSessionRequest$sessionId' => '

ID of a session within the stage.

', 'ListParticipantEventsRequest$sessionId' => '

ID of a session within the stage.

', 'ListParticipantsRequest$sessionId' => '

ID of the session within the stage.

', 'Stage$activeSessionId' => '

ID of the active session within the stage.

', 'StageSession$sessionId' => '

ID of the session within the stage.

', 'StageSessionSummary$sessionId' => '

ID of the session within the stage.

', 'StageSummary$activeSessionId' => '

ID of the active session within the stage.

', ], ], 'StageSessionList' => [ 'base' => NULL, 'refs' => [ 'ListStageSessionsResponse$stageSessions' => '

List of matching stage sessions.

', ], ], 'StageSessionSummary' => [ 'base' => '

Summary information about a stage session.

', 'refs' => [ 'StageSessionList$member' => NULL, ], ], 'StageSummary' => [ 'base' => '

Summary information about a stage.

', 'refs' => [ 'StageSummaryList$member' => NULL, ], ], 'StageSummaryList' => [ 'base' => NULL, 'refs' => [ 'ListStagesResponse$stages' => '

List of the matching stages (summary information only).

', ], ], 'String' => [ 'base' => NULL, 'refs' => [ 'ParticipantAttributes$key' => NULL, 'ParticipantAttributes$value' => NULL, 'ParticipantTokenAttributes$key' => NULL, 'ParticipantTokenAttributes$value' => NULL, ], ], 'TagKey' => [ 'base' => NULL, 'refs' => [ 'TagKeyList$member' => NULL, 'Tags$key' => NULL, ], ], 'TagKeyList' => [ 'base' => NULL, 'refs' => [ 'UntagResourceRequest$tagKeys' => '

Array of tags to be removed. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints beyond what is documented there.

', ], ], 'TagResourceRequest' => [ 'base' => NULL, 'refs' => [], ], 'TagResourceResponse' => [ 'base' => NULL, 'refs' => [], ], 'TagValue' => [ 'base' => NULL, 'refs' => [ 'Tags$value' => NULL, ], ], 'Tags' => [ 'base' => NULL, 'refs' => [ 'CreateStageRequest$tags' => '

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

', 'ListTagsForResourceResponse$tags' => '

Tags attached to the resource. Array of maps, each of the form string:string (key:value).

', 'Stage$tags' => '

', 'StageSummary$tags' => '

', 'TagResourceRequest$tags' => '

Array of tags to be added or updated. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints beyond what is documented there.

', ], ], 'Time' => [ 'base' => NULL, 'refs' => [ 'Event$eventTime' => '

ISO 8601 timestamp (returned as a string) for when the event occurred.

', 'Participant$firstJoinTime' => '

ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.

', 'ParticipantSummary$firstJoinTime' => '

ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.

', 'StageSession$endTime' => '

ISO 8601 timestamp (returned as a string) when the stage session ended. This is null if the stage is active.

', 'StageSession$startTime' => '

ISO 8601 timestamp (returned as a string) when this stage session began.

', 'StageSessionSummary$endTime' => '

ISO 8601 timestamp (returned as a string) when the stage session ended. This is null if the stage is active.

', 'StageSessionSummary$startTime' => '

ISO 8601 timestamp (returned as a string) when this stage session began.

', ], ], 'UntagResourceRequest' => [ 'base' => NULL, 'refs' => [], ], 'UntagResourceResponse' => [ 'base' => NULL, 'refs' => [], ], 'UpdateStageRequest' => [ 'base' => NULL, 'refs' => [], ], 'UpdateStageResponse' => [ 'base' => NULL, 'refs' => [], ], 'UserId' => [ 'base' => NULL, 'refs' => [ 'ListParticipantsRequest$filterByUserId' => '

Filters the response list to match the specified user ID. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request. A userId is a customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems.

', 'Participant$userId' => '

', 'ParticipantSummary$userId' => '

', ], ], 'ValidationException' => [ 'base' => '

', 'refs' => [], ], 'errorMessage' => [ 'base' => NULL, 'refs' => [ 'AccessDeniedException$exceptionMessage' => '

User does not have sufficient access to perform this action.

', 'ConflictException$exceptionMessage' => '

Updating or deleting a resource can cause an inconsistent state.

', 'InternalServerException$exceptionMessage' => '

Unexpected error during processing of request.

', 'PendingVerification$exceptionMessage' => '

Your account is pending verification.

', 'ResourceNotFoundException$exceptionMessage' => '

Request references a resource which does not exist.

', 'ServiceQuotaExceededException$exceptionMessage' => '

Request would cause a service quota to be exceeded.

', 'ValidationException$exceptionMessage' => '

The input fails to satisfy the constraints specified by an Amazon Web Services service.

', ], ], ],];