Microsoft Azure Rendering Session API

openapi: 3.2.0
info:
  description: 'Describing the Azure Remote Rendering REST API for rendering sessions and asset conversions.


    All requests to these APIs must be authenticated using the Secure Token Service as described in the Azure Remote rendering documentation chapter about authentication.'
  title: Microsoft Azure MixedRealityRemoteRendering Rendering…
  version: 2021-01-01-preview
security:
- MrcBearerAuth: []
tags:
- name: Rendering Session
paths:
  /accounts/{account_id}/sessions/{session_id}:
    put:
      operationId: microsoftAzureRemoterenderingCreatesession
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/session_id'
      x-ms-examples:
        Create a rendering session:
          $ref: ./examples/CreateSession.json
      responses:
        '200':
          description: OK. Indicates that there was already a session with the same settings present. This is expected when session creation is retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/session_properties'
        '201':
          description: Created. The session was created successfully.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/session_properties'
        '400':
          description: Bad Request. Returned error object describes which issues occurred.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '409':
          description: Conflict. A rendering session with the ID already exists for the remote rendering account.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Creates A New Rendering Session
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_session_settings'
        description: Settings of the session to be created.
        required: true
    get:
      operationId: microsoftAzureRemoterenderingGetsession
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/session_id'
      x-ms-examples:
        Get a previously created session by ID:
          $ref: ./examples/GetSession.json
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/session_properties'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Gets The Properties Of A Particular Rendering Session
      description: Needs a more full description created.
    patch:
      operationId: microsoftAzureRemoterenderingUpdatesession
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/session_id'
      x-ms-examples:
        Update a session:
          $ref: ./examples/UpdateSession.json
      responses:
        '200':
          description: OK. Session has been updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/session_properties'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '422':
          description: Unprocessable Entity. The maxLeaseTimeMinutes value was invalid. It has to be bigger than the current value of maxLeaseTimeMinutes.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Updates The Max Lease Time Of A Particular Rendering Session
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_session_settings'
        description: Settings used to update the session.
        required: true
  /accounts/{account_id}/sessions/{session_id}/:stop:
    post:
      operationId: microsoftAzureRemoterenderingStopsession
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/session_id'
      x-ms-examples:
        Stop a session:
          $ref: ./examples/StopSession.json
      responses:
        '204':
          description: NoContent. Stop request was successful. The rendering session is stopped.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Stops A Particular Rendering Session
      description: Needs a more full description created.
  /accounts/{account_id}/sessions:
    get:
      operationId: microsoftAzureRemoterenderingListsessions
      x-ms-pageable:
        itemName: sessions
        nextLinkName: '@nextLink'
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      x-ms-examples:
        List sessions:
          $ref: ./examples/ListSessions.json
      responses:
        '200':
          description: OK. Returns the list of sessions which are in a 'Starting' or 'Ready' state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sessions_list'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Gets A List Of All Rendering Sessions
      description: Needs a more full description created.
components:
  schemas:
    session_status:
      enum:
      - Error
      - Expired
      - Starting
      - Ready
      - Stopped
      x-ms-enum:
        name: session_status
        modelAsString: true
        values:
        - value: Error
          description: The rendering session has encountered an error, and is unusable. This is a terminal state.
        - value: Expired
          description: The rendering session enters the 'Expired' state when it has been in the 'Ready' state longer than its lease time. This is a terminal state.
        - value: Starting
          description: The rendering session is starting, but not accepting incoming connections yet.
        - value: Ready
          description: The rendering session is ready for incoming connections.
        - value: Stopped
          description: The rendering session has been stopped with the 'Stop Session' operation. This is a terminal state.
      type: string
      example: Ready
      description: The status of the rendering session. Terminal states are 'Error', 'Expired', and 'Stopped'.
    sessions_list:
      description: The result of a list sessions request.
      type: object
      properties:
        sessions:
          type: array
          description: The list of rendering sessions. Does not include sessions in 'Stopped' state.
          items:
            $ref: '#/components/schemas/session_properties'
        '@nextLink':
          description: If more rendering sessions are available this field will contain a URL where the next batch of sessions can be requested. This URL will need the same authentication as all calls to the Azure Remote Rendering API.
          type: string
          readOnly: true
      required:
      - sessions
    create_session_settings:
      description: Settings of the session to be created.
      properties:
        maxLeaseTimeMinutes:
          example: 60
          type: integer
          description: The time in minutes the session will run after reaching the 'Ready' state. It has to be between 0 and 1440.
        size:
          $ref: '#/components/schemas/session_size'
      type: object
      required:
      - maxLeaseTimeMinutes
      - size
    session_properties:
      description: The properties of a rendering session.
      properties:
        id:
          example: contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28
          type: string
          description: The ID of the session supplied when the session was created.
        arrInspectorPort:
          example: 50052
          maximum: 65534
          minimum: 49152
          type: integer
          description: The TCP port at which the Azure Remote Rendering Inspector tool is hosted.
          readOnly: true
        handshakePort:
          example: 50051
          maximum: 65534
          minimum: 49152
          type: integer
          description: The TCP port used for the handshake when establishing a connection.
          readOnly: true
        elapsedTimeMinutes:
          description: Amount of time in minutes the session is or was in the 'Ready' state. Time is rounded down to a full minute.
          example: 10
          type: integer
          readOnly: true
        hostname:
          example: d4cefb7b-10b9-4631-934d-67445ffa9126.remoterenderingvm.westus2.mixedreality.azure.com
          type: string
          description: The hostname under which the rendering session is reachable.
          readOnly: true
        maxLeaseTimeMinutes:
          type: integer
          description: The time in minutes the session will run after reaching the 'Ready' state.
          example: 60
          readOnly: true
        size:
          $ref: '#/components/schemas/session_size'
          example: Standard
        status:
          $ref: '#/components/schemas/session_status'
          example: Ready
        teraflops:
          example: 10.6
          format: float
          type: number
          description: The computational power of the rendering session GPU measured in teraflops.
          readOnly: true
        error:
          description: The error object containing details about the rendering session startup failure.
          type:
          - object
          - 'null'
          $ref: '#/components/schemas/error'
          example: null
          readOnly: true
        creationTime:
          type: string
          format: date-time
          description: The time when the rendering session was created. Date and time in ISO 8601 format.
          readOnly: true
      type: object
      required:
      - id
      - size
      - status
    error:
      description: The error object containing details of why the request failed.
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: A human-readable representation of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/error'
          description: An array of details about specific errors that led to this reported error.
          readOnly: true
        target:
          description: The target of the particular error (e.g., the name of the property in error).
          type: string
          readOnly: true
        innerError:
          type: object
          $ref: '#/components/schemas/error'
          description: An object containing more specific information than the current object about the error.
          readOnly: true
      type: object
      required:
      - code
      - message
    update_session_settings:
      description: Settings used to update the session.
      type: object
      properties:
        maxLeaseTimeMinutes:
          description: Update to the time the session will run after it reached the 'Ready' state. It has to be larger than the current value of maxLeaseTimeMinutes and less than 1440.
          example: 72
          type: integer
      required:
      - maxLeaseTimeMinutes
    session_size:
      enum:
      - Standard
      - Premium
      x-ms-enum:
        name: session_size
        modelAsString: true
        values:
        - value: Standard
          description: Standard rendering session size.
        - value: Premium
          description: Premium rendering session size.
      example: Standard
      type: string
      description: The size of the server used for the rendering session. The size impacts the number of polygons the server can render. Refer to https://docs.microsoft.com/azure/remote-rendering/reference/vm-sizes for details.
    error_response:
      description: The error response containing details of why the request failed.
      properties:
        error:
          description: The error object containing details of why the request failed.
          type: object
          $ref: '#/components/schemas/error'
      type: object
      required:
      - error
  parameters:
    session_id:
      name: session_id
      description: An ID uniquely identifying the rendering session for the given account. The ID is case sensitive, can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 256 characters.
      in: path
      required: true
      x-example: contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28
      x-ms-parameter-location: method
      schema:
        type: string
    api_version:
      name: api-version
      in: query
      description: The API version to be used with the HTTP request.
      required: true
      x-example: 2021-01-01-preview
      x-ms-parameter-location: method
      schema:
        type: string
    account_id:
      name: account_id
      description: The Azure Remote Rendering account ID.
      in: path
      required: true
      x-example: 30ea64bd-100f-4bf0-adc9-29fa45d4880c
      x-ms-parameter-location: method
      schema:
        type: string
        format: uuid
  securitySchemes:
    MrcBearerAuth:
      in: header
      name: Authorization
      type: apiKey
      description: A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'