openapi: "3.0.0"
info:
  description: "DCV Session Manager API"
  version: "2021.3"
  title: "DCV Session Manager"
tags:
  - name: "sessions"
    description: "Handling sessions"
    externalDocs:
      description: "Find out more"
      url: "https://docs.aws.amazon.com/dcv/latest/adminguide/managing-sessions.html"
  - name: "sessionPermissions"
    description: "Handling session permissions"
    externalDocs:
      description: "Find out more"
      url: "https://docs.aws.amazon.com/dcv/latest/adminguide/security-authorization-file-create.html"
paths:
  /describeSessions:
    post:
      tags:
        - "sessions"
      summary: "Finds all sessions"
      description: "Find all sessions data"
      operationId: "describeSessions"
      requestBody:
        description: "Describe sessions request data"
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescribeSessionsRequestData"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DescribeSessionsResponse"
  /describeServers:
    post:
      tags:
        - "servers"
      summary: "Finds all servers"
      description: "Finds all servers data"
      operationId: "describeServers"
      requestBody:
        description: "Describe servers request data"
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescribeServersRequestData"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DescribeServersResponse"
  /createSessions:
    post:
      tags:
        - "sessions"
      summary: "Creates new sessions"
      description: "API that creates new sessions"
      operationId: "createSessions"
      requestBody:
        description: "Sessions to create"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/CreateSessionRequestData"
      responses:
        "200":
          description: "Successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSessionsResponse"
        "400":
          description: "Invalid input"
  /deleteSessions:
    post:
      tags:
        - "sessions"
      summary: "Deletes sessions"
      description: "Deletes the sessions requested"
      operationId: "deleteSessions"
      requestBody:
        description: "Sessions to delete"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/DeleteSessionRequestData"
      responses:
        "200":
          description: "Successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteSessionsResponse"
        "400":
          description: "Invalid input"
  /sessionPermissions:
    put:
      tags:
        - "sessionPermissions"
      summary: "Update session permissions"
      description: "API that update session permissions"
      operationId: "updateSessionPermissions"
      requestBody:
        description: "Sessions to update"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/UpdateSessionPermissionsRequestData"
      responses:
        "200":
          description: "Successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateSessionPermissionsResponse"
        "400":
          description: "Invalid input"
  /sessionConnectionData/{sessionId}/{user}:
    get:
      tags:
        - "GetSessionConnectionData"
      summary: "Gets the information to connect to a session"
      operationId: "GetSessionConnectionData"
      parameters:
        - name: "sessionId"
          in: "path"
          description: "Session id to get connection details for"
          required: true
          schema:
            type: "string"
        - name: "user"
          in: "path"
          description: "User to get the connection token for"
          required: true
          schema:
            type: "string"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSessionConnectionDataResponse"
        "400":
          description: "Invalid input"
  /getSessionScreenshots:
    post:
      tags:
        - "sessions"
      summary: "Gets session screenshots"
      description: "Gets session screenshots"
      operationId: "getSessionScreenshots"
      requestBody:
        description: "GetSessionScreenshots request data"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/GetSessionScreenshotRequestData"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSessionScreenshotsResponse"
        "400":
          description: "Invalid input"
  /openServers:
    post:
      tags:
        - "servers"
      summary: "Open a server for placement"
      description: "Open a server for placement"
      operationId: "openServers"
      requestBody:
        description: "OpenServers request data"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/OpenServerRequestData"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenServersResponse"
        "400":
          description: "Invalid input"
  /closeServers:
    post:
      tags:
        - "servers"
      summary: "Close a server for placement"
      description: "Close a server for placement"
      operationId: "closeServers"
      requestBody:
        description: "CloseServers request data"
        required: true
        content:
          application/json:
            schema:
              type: "array"
              items:
                $ref: "#/components/schemas/CloseServerRequestData"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CloseServersResponse"
        "400":
          description: "Invalid input"
components:
  schemas:
    KeyValuePair:
      type: "object"
      description: "A generic key/value pair"
      properties:
        Key:
          description: "The key of the pair"
          type: "string"
        Value:
          description: "The value of the pair"
          type: "string"
    Server:
      type: "object"
      description: "The entity representing a server in DCV Session Manager"
      properties:
        Id:
          description: "The id of the server"
          type: "string"
        Ip:
          description: "The ip of the server"
          type: "string"
        Hostname:
          description: "The hostname of the server"
          type: "string"
        DefaultDnsName:
          description: "The default DNS name of the server"
          type: "string"
        Port:
          description: "The port where the server listens. This field is deprecated and replaced by PortTcp"
          type: "string"
        Endpoints:
          description: "The array representing DCV endpoints"
          type: "array"
          items:
            $ref: "#/components/schemas/Endpoint"
        WebUrlPath:
          description: "The server web url path"
          type: "string"
        Version:
          description: "The version of the server"
          type: "string"
        SessionManagerAgentVersion:
          description: "The version of the session manager agent"
          type: "string"
        Availability:
          description: "The server availability"
          type: "string"
          enum: [AVAILABLE, UNAVAILABLE]
        UnavailabilityReason:
          description: "The unavailability reason"
          type: "string"
          enum: [SERVER_FULL, SERVER_CLOSED, UNREACHABLE_AGENT, UNHEALTHY_DCV_SERVER, EXISTING_LOGGED_IN_USER, UNKNOWN]
        ConsoleSessionCount:
          description: "The count of console session on the server"
          type: "integer"
          format: "int32"
        VirtualSessionCount:
          description: "The count of virtual session on the server"
          type: "integer"
          format: "int32"
        Host:
          description: "The information about the host"
          type: "object"
          $ref: "#/components/schemas/Host"
        Tags:
          description: "The tags of the server"
          type: "array"
          xml:
            name: "tag"
            wrapped: true
          items:
            $ref: "#/components/schemas/KeyValuePair"
      xml:
        name: "Server"
    Endpoint:
      type: "object"
      description: "The entity representing an endpoint in DCV"
      properties:
        Port:
          description: "The port of the DCV endpoint"
          type: "integer"
        WebUrlPath:
          description: "The web url path of the DCV endpoint"
          type: "string"
        Protocol:
          description: "The protocol of the DCV endpoint"
          type: "string"
          enum: [HTTP, QUIC]
    Host:
      type: "object"
      description: "The entity representing an host in DCV Session Manager"
      properties:
        Os:
          description: "The entity representing OS information"
          type: "object"
          $ref: "#/components/schemas/Os"
        Memory:
          description: "The metrics about memory"
          type: "object"
          $ref : "#/components/schemas/Memory"
        Swap:
          description: "The metrics about swap"
          type: "object"
          $ref : "#/components/schemas/Swap"
        Aws:
          description: "The information about AWS"
          type: "object"
          $ref: "#/components/schemas/Aws"
        CpuInfo:
          description: "The metrics about cpu"
          type: "object"
          $ref: "#/components/schemas/CpuInfo"
        CpuLoadAverage:
          description: "The array containing disk information"
          type: "object"
          $ref: "#/components/schemas/CpuLoadAverage"
        Gpus:
          description: "The array containing GPU information"
          type: "array"
          items:
            $ref: "#/components/schemas/Gpu"
        LoggedInUsers:
          description: "The array containing users information"
          type: "array"
          items:
            $ref: "#/components/schemas/LoggedInUser"
      xml:
        name: "Host"
    Os:
      description: "The metrics about the Os"
      type: "object"
      properties:
        Family:
          description: "The OS family"
          type: "string"
        Name:
          description: "The name of the OS"
          type: "string"
        Version:
          description: "The version of the OS"
          type: "string"
        KernelVersion:
          description: "The version of the Kernel"
          type: "string"
        BuildNumber:
          description: "The OS build number"
          type: "string"
    Memory:
      description: "The metrics about memory"
      type: "object"
      properties:
        TotalBytes:
          description: "The total bytes"
          type: "integer"
          format: "int64"
        UsedBytes:
          description: "The used bytes"
          type: "integer"
          format: "int64"
    Swap:
      description: "The metrics about swap"
      type: "object"
      properties:
        TotalBytes:
          description: "The total bytes"
          type: "integer"
          format: "int64"
        UsedBytes:
          description: "The used bytes"
          type: "integer"
          format: "int64"
    CpuInfo:
      description: "The entity representing cpu information"
      type: "object"
      properties:
        Vendor:
          description: "The vendor of the cpu"
          type: "string"
        ModelName:
          description: "The model name of the cpu"
          type: "string"
        Architecture:
          description: "The architecture of the cpu"
          type: "string"
        NumberOfCpus:
          description: "The number of cpus"
          type: "integer"
        PhysicalCoresPerCpu:
          description: "The physical core count per cpu"
          type: "integer"
    CpuLoadAverage:
      description: "The entity representing cpu load average information"
      type: "object"
      properties:
        OneMinute:
          description: "The average load in the last minute of the cpu"
          type: "number"
          format: "float"
        FiveMinutes:
          description: "The average load in the last 5 minutes of the cpu"
          type: "number"
          format: "float"
        FifteenMinutes:
          description: "The average load in the last 15 minutes of the cpu"
          type: "number"
          format: "float"
    Gpu:
      description: "The entity representing gpu information"
      type: "object"
      properties:
        Vendor:
          description: "The vendor of the gpu"
          type: "string"
        ModelName:
          description: "The model name of the gpu"
          type: "string"
    LoggedInUser:
      description: "The entity representing the logged in user information"
      type: "object"
      properties:
        Username:
          description: "The username of the logged in user"
          type: "string"
    Aws:
      description: "The entity representing aws information"
      type: "object"
      properties:
        Region:
          description: "The AWS region"
          type: "string"
        EC2InstanceType:
          description: "The AWS EC2 instance type"
          type: "string"
        EC2InstanceId:
          description: "The AWS EC2 instance id"
          type: "string"
        EC2ImageId:
          description: "The AWS EC2 image id"
          type: "string"
    Session:
      description: "The entity that represents a session in DCV session manager"
      type: "object"
      properties:
        Id:
          description: "The id of the session"
          type: "string"
        Name:
          description: "The descriptive name of the session"
          type: "string"
          example: "test1"
        Owner:
          description: "The owner of the session"
          type: "string"
          example: "barbara"
        Server:
          description: "The server in which the session is"
          $ref: "#/components/schemas/Server"
        Type:
          description: "The session type (Virtual or Console)"
          type: string
        MaxConcurrentClients:
          description: "The number of max concurrent clients that can log to a session"
          type: "integer"
          format: "int64"
        State:
          description: "The session state"
          type: string
        StateReason:
          description: "The reason for the current state of the session"
          type: string
        CreationTime:
          description: "The session creation time"
          type: string
          format: date-time
        LastDisconnectionTime:
          description: "The last session disconnection time"
          type: string
          format: date-time
        NumOfConnections:
          description: "The number of connection to this DCV session."
          type: "integer"
          format: "int64"
        StorageRoot:
          description: "Specifies the path to the folder used for session storage."
          type: string
      xml:
        name: "Session"
    DescribeSessionsRequestData:
      description: "The entity that represents the data that the user pass for describing the sessions"
      properties:
        SessionIds:
          description: "The session ids"
          type: "array"
          items:
            type: "string"
        Filters:
          description: "The filters. Filters supported: owner, tag:key. 'owner' The session owner to filter by. 'tag:key' The key/value combination of a tag assigned to the server. Use the tag key in the filter name and the tag value as the filter value. For example, to find all sessions that have a tag with the key City and the value London , specify tag:City for the filter name and London for the filter value."
          type: "array"
          items:
            $ref: "#/components/schemas/KeyValuePair"
        MaxResults:
          description: "Number of results to show, if provided must be between 1 and 1000"
          type: "integer"
        NextToken:
          description: "the pagination token"
          type: "string"
    DescribeSessionsResponse:
      description: "The response to a describeSession request"
      type: "object"
      properties:
        RequestId:
          description: "DescribeSessions request id"
          type: "string"
        Sessions:
          type: "array"
          description: "The array of sessions described"
          items:
            $ref: "#/components/schemas/Session"
        NextToken:
          description: "The token used for pagination"
          type: "string"
    DescribeServersRequestData:
      description: "The entity that represents the data that the user pass for describing servers"
      properties:
        ServerIds:
          description: "The server ids"
          type: "array"
          items:
            type: "string"
        MaxResults:
          description: "Number of results to show, if provided must be between 1 and 1000"
          type: "integer"
        NextToken:
          description: "the pagination token"
          type: "string"
    DescribeServersResponse:
      description: "The response to a describeServers request"
      type: "object"
      properties:
        RequestId:
          description: "DescribeServers request id"
          type: "string"
        Servers:
          type: "array"
          description: "The array of servers described"
          items:
            $ref: "#/components/schemas/Server"
        NextToken:
          description: "The token used for pagination"
          type: "string"
    CreateSessionRequestData:
      description: "The entity that represents the data that the user pass for creating a session in DCV session manager, an array of those entry forms the createSessionsRequest"
      properties:
        Name:
          description: "The descriptive name of the session"
          type: "string"
          example: "test1"
        Owner:
          description: "The owner of the session"
          type: "string"
          example: "barbara"
        Type:
          description: "The session type (Virtual or Console)"
          type: string
        DcvGlEnabled:
          description: "The property that specifies if dcv-gl is enabled"
          type: boolean
        MaxConcurrentClients:
          description: "The number of max concurrent clients that can log to a session"
          type: "integer"
          format: "int64"
        InitFilePath:
          description: "The init file path on the DCV host. This field is deprecated and replaced by InitFile"
          type: "string"
          deprecated: true
        InitFile:
          description: "File on the DCV host to be used to initialize the session instead of the default. If it is not a simple filename, it must be a relative path to the init directory configured on the DCV host."
          type: "string"
        AutorunFile:
          description: "File on the DCV host to be automatically executed within the session. If it is not a simple filename, it must be a relative path to the autorun directory configured on the DCV host."
          type: "string"
        AutorunFileArguments:
          description: "Command-line arguments to be passed to the file defined in AutorunFile when it is executed."
          type: "array"
          items:
            type: "string"
        PermissionsFile:
          description: "The permissions file"
          type: "string"
        Requirements:
          description: "The required tags for the session. Example: ram_gb = '4' and software='my software'. The escape char is ', example irish_name='o''neil' "
          type: "string"
        EnqueueRequest:
          description: "The request is enqueued if no DCV server are available for placement. If this field is not set, the default is false."
          type: boolean
        DisableRetryOnFailure:
          description: "Disable automatic retry of the request if session creation fails. If this field is not set, the default is false."
          type: boolean
        StorageRoot:
          description: "Specifies the path to the folder used for session storage."
          type: string
    UnsuccessfulCreateSessionRequestData:
      description: "Data representing an unsuccessful request"
      type: "object"
      properties:
        CreateSessionRequestData:
          description: "The data related to the failure request"
          $ref: "#/components/schemas/CreateSessionRequestData"
        FailureReason:
          description: "The failure reason"
          type: "string"
    CreateSessionsResponse:
      description: "The response to a createSessions request"
      type: "object"
      properties:
        RequestId:
          description: "CreateSessions request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of sessions that are in process of being created"
          items:
            $ref: "#/components/schemas/Session"
        UnsuccessfulList:
          type: "array"
          description: "The array of sessions that cannot be created"
          items:
            $ref: "#/components/schemas/UnsuccessfulCreateSessionRequestData"
    DeleteSessionSuccessfulResponse:
      description: "The successful response of a delete session"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
        State:
          description: "The session state"
          type: "string"
    DeleteSessionUnsuccessfulResponse:
      description: "The unsuccessful response of a delete session"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
        FailureReason:
          description: "The failure reason"
          type: "string"
    UpdateSessionPermissionsSuccessfulResponse:
      description: "The successful response of a update session permissions"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
    UpdateSessionPermissionsUnsuccessfulResponse:
      description: "The unsuccessful response of a update session permissions"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
        FailureReason:
          description: "The failure reason"
          type: "string"
    DeleteSessionsResponse:
      description: "The response to a deleteSessions request"
      type: "object"
      properties:
        RequestId:
          description: "DeleteSessions request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of sessions that are in process of being deleted"
          items:
            $ref: "#/components/schemas/DeleteSessionSuccessfulResponse"
        UnsuccessfulList:
          type: "array"
          description: "The array of sessions that cannot be deleted"
          items:
            $ref: "#/components/schemas/DeleteSessionUnsuccessfulResponse"
    DeleteSessionRequestData:
      description: "The entity that represents the data that the user pass for deleting a session in DCV session manager, an array of those entry forms the deleteSessionRequest"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
        Owner:
          description: "The owner"
          type: "string"
        Force:
          description: "The parameter to force a deletion"
          type: "boolean"
          default: "false"
    UpdateSessionPermissionsRequestData:
      description: "The entity that represents the data that the user pass for updating the permissions of a session in DCV session manager, an array of those entry forms the updateSessionPermissionsRequest"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
        Owner:
          description: "The owner"
          type: "string"
        PermissionsFile:
          description: "The permissions file base64 encoded"
          type: "string"
    UpdateSessionPermissionsResponse:
      description: "The update session permission response"
      properties:
        RequestId:
          description: "UpdateSessionPermissions request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of sessions that are in process of having the permissions updated"
          items:
            $ref: "#/components/schemas/UpdateSessionPermissionsSuccessfulResponse"
        UnsuccessfulList:
          type: "array"
          description: "The array of sessions that cannot have the permissions updated"
          items:
            $ref: "#/components/schemas/UpdateSessionPermissionsUnsuccessfulResponse"
    GetSessionConnectionDataResponse:
      description: "The get session connection data response"
      type: "object"
      properties:
        Session:
          description: "Session to connect to"
          $ref: "#/components/schemas/Session"
        ConnectionToken:
          description: "The token used to connect to the session"
          type: "string"
    GetSessionScreenshotRequestData:
      description: "The entity that represents the data that the user pass for getting the session screenshot"
      properties:
        SessionId:
          description: "The session id"
          type: "string"
    GetSessionScreenshotsResponse:
      description: "The response to a getSessionScreenshots request"
      type: "object"
      properties:
        RequestId:
          description: "GetSessionScreenshots request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of session screenshots successfully retrieved"
          items:
            $ref: "#/components/schemas/GetSessionScreenshotSuccessfulResponse"
        UnsuccessfulList:
          type: "array"
          description: "The array of session screenshots that cannot be retrieved"
          items:
            $ref: "#/components/schemas/GetSessionScreenshotUnsuccessfulResponse"
    GetSessionScreenshotSuccessfulResponse:
      description: "The entity that represents a DCV session screenshot"
      type: "object"
      properties:
        SessionScreenshot:
          description: "The session screenshot"
          $ref: "#/components/schemas/SessionScreenshot"
    SessionScreenshot:
      description: "The entity that represents a DCV session screenshot"
      type: "object"
      properties:
        SessionId:
          description: "The id of the session"
          type: "string"
        Images:
          type: "array"
          description: "The array of session screenshots"
          items:
            $ref: "#/components/schemas/SessionScreenshotImage"
      xml:
        name: "SessionScreenshot"
    SessionScreenshotImage:
      description: "Data representing a single DCV session screenshot"
      properties:
        Format:
          description: "The image format. Supported formats: jpeg, png"
          type: "string"
          example: "jpeg"
        Data:
          description: "The base64 image data"
          type: "string"
          example: "997987/8kgj49ikjhewkwwe0008084EXAMPLE"
        CreationTime:
          description: "The session screen creation time"
          type: string
          format: date-time
        Primary:
          description: "Tells if the image belongs to the primary screen"
          type: boolean
    GetSessionScreenshotUnsuccessfulResponse:
      description: "Data representing an unsuccessful get session screenshot request"
      type: "object"
      properties:
        GetSessionScreenshotRequestData:
          description: "The data related to the failure request"
          $ref: "#/components/schemas/GetSessionScreenshotRequestData"
        FailureReason:
          description: "The failure reason"
          type: "string"
    OpenServerRequestData:
      description: "The entity that represents the data that the user pass to open a server"
      properties:
        ServerId:
          description: "The server id"
          type: "string"
    OpenServersResponse:
      description: "The response to an openServers request"
      type: "object"
      properties:
        RequestId:
          description: "OpenServers request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of servers successfully open"
          items:
            $ref: "#/components/schemas/OpenServerSuccessfulResponse"
        UnsuccessfulList:
          type: "array"
          description: "The array of servers that cannot be open"
          items:
            $ref: "#/components/schemas/OpenServerUnsuccessfulResponse"
    OpenServerSuccessfulResponse:
      description: "Data representing a successful open server request"
      type: "object"
      properties:
        ServerId:
          description: "The server id"
          type: "string"
    OpenServerUnsuccessfulResponse:
      description: "Data representing an unsuccessful open server request"
      type: "object"
      properties:
        OpenServerRequestData:
          description: "The data related to the failure request"
          $ref: "#/components/schemas/OpenServerRequestData"
        FailureCode:
          description: "The failure code"
          type: "string"
        FailureReason:
          description: "The failure reason"
          type: "string"
    CloseServerRequestData:
      description: "The entity that represents the data that the user pass to close a server"
      properties:
        ServerId:
          description: "The server id"
          type: "string"
        Force:
          description: "Force the close operation, if force is false the server is close only if no sessions are sunning on it. Defaults to false if not provided"
          type: "boolean"
    CloseServersResponse:
      description: "The response to a closeServers request"
      type: "object"
      properties:
        RequestId:
          description: "CloseServers request id"
          type: "string"
        SuccessfulList:
          type: "array"
          description: "The array of servers successfully closed"
          items:
            $ref: "#/components/schemas/CloseServerSuccessfulResponse"
        UnsuccessfulList:
          type: "array"
          description: "The array of servers that cannot be closed"
          items:
            $ref: "#/components/schemas/CloseServerUnsuccessfulResponse"
    CloseServerSuccessfulResponse:
      description: "Data representing a successful close server request"
      type: "object"
      properties:
        ServerId:
          description: "The server id"
          type: "string"
    CloseServerUnsuccessfulResponse:
      description: "Data representing an unsuccessful close server request"
      type: "object"
      properties:
        CloseServerRequestData:
          description: "The data related to the failure request"
          $ref: "#/components/schemas/CloseServerRequestData"
        FailureCode:
          description: "The failure code"
          type: "string"
        FailureReason:
          description: "The failure reason"
          type: "string"
