---
title: "POST /CreateStage"
method: POST
path: "/CreateStage"
---

# POST /CreateStage

`POST /CreateStage`

Creates a new stage (and optionally participant tokens).

## Request body

- object
  - `name` string — Optional name that can be specified for the stage being created.
  - `participantTokenConfigurations` ParticipantTokenConfiguration[] — Array of participant token configuration objects to attach to the new stage.
    - `duration` integer — Duration (in minutes), after which the corresponding participant token expires. Default: 720 (12 hours).
    - `userId` string — 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. <i>This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.</i>
    - `attributes` object — 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. <i>This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.</i>
    - `capabilities` ParticipantTokenCapability[] — Set of capabilities that the user is allowed to perform in the stage.
  - `tags` object — Tags attached to the resource. Array of maps, each of the form <code>string:string (key:value)</code>. See <a href="https://docs.aws.amazon.com/tag-editor/latest/userguide/best-practices-and-strats.html">Best practices and strategies</a> in <i>Tagging AWS Resources and Tag Editor</i> 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.
  - `autoParticipantRecordingConfiguration` object — Object specifying a configuration for individual participant recording.
    - `storageConfigurationArn` string — ARN of the <a>StorageConfiguration</a> resource to use for individual participant recording. Default: <code>""</code> (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a <a>Stage</a> is created or updated. To disable individual participant recording, set this to <code>""</code>; other fields in this object will get reset to their defaults when sending <code>""</code>.
    - `mediaTypes` ParticipantRecordingMediaType[] — Types of media to be recorded. Default: <code>AUDIO_VIDEO</code>.
    - `thumbnailConfiguration` object — A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
      - `targetIntervalSeconds` integer — The targeted thumbnail-generation interval in seconds. This is configurable only if <code>recordingMode</code> is <code>INTERVAL</code>. Default: 60.
      - `storage` ThumbnailStorageType[] — Indicates the format in which thumbnails are recorded. <code>SEQUENTIAL</code> records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. <code>LATEST</code> saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by <code>targetIntervalSeconds</code>. You can enable both <code>SEQUENTIAL</code> and <code>LATEST</code>. Default: <code>SEQUENTIAL</code>.
      - `recordingMode` 'INTERVAL' | 'DISABLED' — Thumbnail recording mode. Default: <code>DISABLED</code>.
    - `recordingReconnectWindowSeconds` integer — <p>If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.</p> <p>The default value is 0, which disables merging.</p>
    - `hlsConfiguration` object — HLS configuration object for individual participant recording.
      - `targetSegmentDurationSeconds` integer — Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
    - `recordParticipantReplicas` boolean — Optional field to disable replica participant recording. If this is set to <code>false</code> when a participant is a replica, replica participants are not recorded. Default: <code>true</code>.

## Response `200`

Success

- CreateStageResponse
  - `stage` object — The stage that was created.
    - `arn` string, required — Stage ARN.
    - `name` string — Stage name.
    - `activeSessionId` string — ID of the active session within the stage.
    - `tags` object — Tags attached to the resource. Array of maps, each of the form <code>string:string (key:value)</code>. See <a href="https://docs.aws.amazon.com/tag-editor/latest/userguide/best-practices-and-strats.html">Best practices and strategies</a> in <i>Tagging AWS Resources and Tag Editor</i> 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.
    - `autoParticipantRecordingConfiguration` object — Configuration object for individual participant recording, attached to the stage.
      - `storageConfigurationArn` string, required — ARN of the <a>StorageConfiguration</a> resource to use for individual participant recording. Default: <code>""</code> (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a <a>Stage</a> is created or updated. To disable individual participant recording, set this to <code>""</code>; other fields in this object will get reset to their defaults when sending <code>""</code>.
      - `mediaTypes` ParticipantRecordingMediaType[] — Types of media to be recorded. Default: <code>AUDIO_VIDEO</code>.
      - `thumbnailConfiguration` object — A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
        - `targetIntervalSeconds` integer — The targeted thumbnail-generation interval in seconds. This is configurable only if <code>recordingMode</code> is <code>INTERVAL</code>. Default: 60.
        - `storage` ThumbnailStorageType[] — Indicates the format in which thumbnails are recorded. <code>SEQUENTIAL</code> records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. <code>LATEST</code> saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by <code>targetIntervalSeconds</code>. You can enable both <code>SEQUENTIAL</code> and <code>LATEST</code>. Default: <code>SEQUENTIAL</code>.
        - `recordingMode` 'INTERVAL' | 'DISABLED' — Thumbnail recording mode. Default: <code>DISABLED</code>.
      - `recordingReconnectWindowSeconds` integer — <p>If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.</p> <p>The default value is 0, which disables merging.</p>
      - `hlsConfiguration` object — HLS configuration object for individual participant recording.
        - `targetSegmentDurationSeconds` integer — Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
      - `recordParticipantReplicas` boolean — Optional field to disable replica participant recording. If this is set to <code>false</code> when a participant is a replica, replica participants are not recorded. Default: <code>true</code>.
    - `endpoints` object — Summary information about various endpoints for a stage.
      - `events` string — Events endpoint.
      - `whip` string — The endpoint to be used for IVS real-time streaming using the WHIP protocol.
      - `rtmp` string — The endpoint to be used for IVS real-time streaming using the RTMP protocol.
      - `rtmps` string — The endpoint to be used for IVS real-time streaming using the RTMPS protocol.
  - `participantTokens` ParticipantToken[] — Participant tokens attached to the stage. These correspond to the <code>participants</code> in the request.
    - `participantId` string — Unique identifier for this participant token, assigned by IVS.
    - `token` string, password — The issued client token, encrypted.
    - `userId` string — 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. <i>This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.</i>
    - `attributes` object — 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. <i>This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.</i>
    - `duration` integer — Duration (in minutes), after which the participant token expires. Default: 720 (12 hours).
    - `capabilities` ParticipantTokenCapability[] — Set of capabilities that the user is allowed to perform in the stage.
    - `expirationTime` string, date-time — ISO 8601 timestamp (returned as a string) for when this token expires.

## Other responses

- `480` — ValidationException
- `481` — AccessDeniedException
- `482` — ServiceQuotaExceededException
- `483` — PendingVerification

---

[API](https://skmtc.net/aws/apis/ivs-realtime.md) · [All operations](https://skmtc.net/aws/apis/ivs-realtime/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/ivs-realtime/revisions/f8857274a50f/schema)