API Reference

GET`/v1/desktop/:id`

Get details of a specific desktop instance

Returns the ID, status, creation timestamp, and timeout timestamp for a given desktop instance.

Path Parameters

`id`
Required
string

The UUID of the desktop instance to retrieve

Example: "a1b2c3d4-e5f6-7890-1234-567890abcdef"Format: "uuid"

Header Parameters

`x-api-key`
Required
string

API key for authentication

Example: "api_12345"

Status code	Description
`200`	Desktop instance details retrieved successfully
`400`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401`	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
`403`	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
`404`	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
`409`	This response is sent when a request conflicts with the current state of the server.
`429`	The user has sent too many requests in a given amount of time ("rate limiting")
`500`	The server has encountered a situation it does not know how to handle.
`502`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

curl -X GET "https://api.cyberdesk.io/v1/desktop/:id" \
  -H "x-api-key: api_12345"

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "running",
  "stream_url": "https://cyberdesk.com/vnc/a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "created_at": "2023-10-27T10:00:00Z",
  "timeout_at": "2023-10-28T10:00:00Z"
}

POST`/v1/desktop`

Create a new virtual desktop instance

Creates a new virtual desktop instance and returns its ID and stream URL

Request Body (Optional)

`timeout_ms`integer

Timeout in milliseconds for the desktop session

Example: 3600000

Header Parameters

`x-api-key`
Required
string

API key for authentication

Example: "api_12345"

Status code	Description
`200`	Desktop creation initiated successfully
`400`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401`	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
`403`	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
`404`	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
`409`	This response is sent when a request conflicts with the current state of the server.
`429`	The user has sent too many requests in a given amount of time ("rate limiting")
`500`	The server has encountered a situation it does not know how to handle.
`502`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

curl -X POST "https://api.cyberdesk.io/v1/desktop" \
  -H "x-api-key: api_12345" \
  -d '{
  "timeout_ms": 3600000
}'

{
  "id": "desktop_12345",
  "status": "pending"
}

POST`/v1/desktop/:id/stop`

Stop a running desktop instance

Stops a running desktop instance and cleans up resources

Path Parameters

`id`
Required
string

Desktop instance ID to stop

Example: "desktop_12345"

Header Parameters

`x-api-key`
Required
string

API key for authentication

Example: "api_12345"

Status code	Description
`200`	Desktop stopped successfully
`400`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401`	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
`403`	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
`404`	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
`409`	This response is sent when a request conflicts with the current state of the server.
`429`	The user has sent too many requests in a given amount of time ("rate limiting")
`500`	The server has encountered a situation it does not know how to handle.
`502`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

curl -X POST "https://api.cyberdesk.io/v1/desktop/:id/stop" \
  -H "x-api-key: api_12345"

{
  "status": "terminated"
}

POST`/v1/desktop/:id/computer-action`

Perform an action on the desktop

Executes a computer action such as mouse clicks, keyboard input, or screenshots on the desktop

Request Body (Optional)

`body`Click Mouse Action | Scroll Action | Move Mouse Action | Drag Mouse Action | Type Text Action | Press Keys Action | Wait Action | Screenshot Action | Get Cursor Position Action

Path Parameters

`id`
Required
string

Desktop instance ID to perform the action on

Example: "desktop_12345"

Header Parameters

`x-api-key`
Required
string

API key for authentication

Example: "api_12345"

Status code	Description
`200`	Action executed successfully. Response may contain output or image data depending on the action.
`400`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401`	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
`403`	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
`404`	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
`409`	This response is sent when a request conflicts with the current state of the server.
`429`	The user has sent too many requests in a given amount of time ("rate limiting")
`500`	The server has encountered a situation it does not know how to handle.
`502`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

curl -X POST "https://api.cyberdesk.io/v1/desktop/:id/computer-action" \
  -H "x-api-key: api_12345" \
  -d '{
  "type": "click_mouse",
  "x": 500,
  "y": 300,
  "button": "left",
  "num_of_clicks": 1,
  "click_type": "click"
}'

{
  "output": "X=500 Y=300",
  "error": "Command failed with code 1: xdotool: command not found",
  "base64_image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQ..."
}

POST`/v1/desktop/:id/bash-action`

Execute a bash command on the desktop

Runs a bash command on the desktop and returns the command output

Request Body (Optional)

`command`
Required
string

Bash command to execute

Example: "echo 'Hello, World!'"

Path Parameters

`id`
Required
string

Desktop instance ID to run the command on

Example: "desktop_12345"

Header Parameters

`x-api-key`
Required
string

API key for authentication

Example: "api_12345"

Status code	Description
`200`	Command executed successfully. Response contains command output.
`400`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401`	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
`403`	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
`404`	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
`409`	This response is sent when a request conflicts with the current state of the server.
`429`	The user has sent too many requests in a given amount of time ("rate limiting")
`500`	The server has encountered a situation it does not know how to handle.
`502`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

curl -X POST "https://api.cyberdesk.io/v1/desktop/:id/bash-action" \
  -H "x-api-key: api_12345" \
  -d '{
  "command": "echo 'Hello, World!'"
}'

{
  "output": "X=500 Y=300",
  "error": "Command failed with code 1: xdotool: command not found",
  "base64_image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQ..."
}

API Reference

GET/v1/desktop/:id

idRequiredstring

x-api-keyRequiredstring

Response

Typescript

POST/v1/desktop

timeout_msinteger

x-api-keyRequiredstring

Response

Typescript

POST/v1/desktop/:id/stop

idRequiredstring

x-api-keyRequiredstring

Response

Typescript

POST/v1/desktop/:id/computer-action

bodyClick Mouse Action | Scroll Action | Move Mouse Action | Drag Mouse Action | Type Text Action | Press Keys Action | Wait Action | Screenshot Action | Get Cursor Position Action

Click Mouse Action

Scroll Action

Move Mouse Action

Drag Mouse Action

Type Text Action

Press Keys Action

Wait Action

Screenshot Action

Get Cursor Position Action

idRequiredstring

x-api-keyRequiredstring

Response

Typescript

POST/v1/desktop/:id/bash-action

commandRequiredstring

idRequiredstring

x-api-keyRequiredstring

Response

Typescript

On this page

GET`/v1/desktop/:id`

`id`
Required
string

`x-api-key`
Required
string

POST`/v1/desktop`

`timeout_ms`integer

`x-api-key`
Required
string

POST`/v1/desktop/:id/stop`

`id`
Required
string

`x-api-key`
Required
string

POST`/v1/desktop/:id/computer-action`

`body`Click Mouse Action | Scroll Action | Move Mouse Action | Drag Mouse Action | Type Text Action | Press Keys Action | Wait Action | Screenshot Action | Get Cursor Position Action

`id`
Required
string

`x-api-key`
Required
string

POST`/v1/desktop/:id/bash-action`

`command`
Required
string

`id`
Required
string

`x-api-key`
Required
string