HTTP API¶
HTTP API allows you to get a software access to many features available in your personal account: manage desktops, create scheduled connections.
Requests¶
All requests must be made over the HTTPS (not HTTP) protocol with an appropriate method for each command at https://api.getscreen.me/v1/
Responses¶
Data responses are returned in JSON UTF-8 with ContentType: application/json
. Each response wraps data in the data
JSON container
The API server may return the following HTTP response codes:
HTTP response code | Description |
---|---|
200 OK | Request accepted and processed |
400 Bad Request | Request denied, invalid parameters, error |
402 Payment Required | Request rejected, request limit for the service plan exceeded |
403 Forbidden | Request denied, no access to data |
404 Not Found | Request denied, unknown request URL |
Authentication¶
API is RESTful API: the server doesn’t store the client connection state. That’s why the client must send authorization data each time a request is sent. An API key is used as such data. Add the key in each request in the ?apikey=
GET parameter or in the X-Api-Key
HTTP header
Your API key can be found in your personal profile in the "Integration" section of the HTTP API tab
Methods¶
These are the commands to manage desktops and connections. We’ve divided them into several groups:
- Permanent Access
- Quick Support
- Connections history
Permanent Access¶
Desktop list¶
You can get the full desktop list with the agents/list
method
In the context of API calls, desktops will be referred to as Agents since a desktop is technically managed with an agent
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
search | string | Search by agent name, IP address or group name |
group_id | string | Filter by group ID |
Response:
{
"data":[ {
"id":1001,
"name":"Allesandro Paci",
"group":"Accounting",
"disabled":false,
"limited":false,
"link_time":1587837997,
"last_time":1600374761,
"geo":{
"ip":"2.21.31.68",
"country":"USA",
"region":"California",
"city":"Los Angeles"
},
"permanent_url":"https://go.getscreen.me/paci",
"preview_url":"https://getscreen.me/preview/1245273f5448a704379da46f476564a592efb17c6a7695adde96247cd7874416GbBzRm6SRLMqrP0YoYFMxCopL6NTzvn8.png",
"os":"win",
"version":"1.9.4",
"online":true,
"installed":true,
"favorite":false,
"owner":"john.smith@gmail.com",
"sessions":{
"last":{
"id":148505,
"start_time":1600343858,
"stop_time":1600343900,
"client":{
"ip":"188.162.195.82",
"country":"Russian Federation",
"region":"Tatarstan",
"city":"Kazan",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
}
},
"total":121
}
}, ... ]
}
Response data:
Name | Type | Description |
---|---|---|
id | number | Internal system ID |
name | string | Name |
group | string | Group |
disabled | boolean | Is the agent blocked? |
limited | boolean | Is the agent limited? |
link_time | unixtime | Added to personal account date and time |
last_time | unixtime | Last active date and time |
geo | object | Location |
geo.ip | string | IP address |
geo.country | string | Country |
geo.region | string | Region |
geo.city | string | City |
permanent_url | string | Permanent connection URL |
onetime_url | string | URL for one-time connection |
preview_url | string | Desktop preview download URL |
os | string | Operating system. Possible values: win , mac , linux and android |
version | string | Agent version |
online | boolean | Current active state |
installed | boolean | Is the agent installed on the desktop? |
favorite | boolean | Is this a favorited desktop from the personal account? |
owner | string | Desktop access system owner account |
sessions | object | Connection info |
sessions.last | object | Last connection |
sessions.last.id | number | Internal system connection ID |
sessions.last.start_time | unixtime | Connection start date and time |
sessions.last.stop_time | unixtime | Connection stop date and time |
sessions.last.client | object | Client info (connection creator) |
sessions.last.client.ip | string | IP address |
sessions.last.client.country | string | Country |
sessions.last.client.region | string | Region |
sessions.last.client.city | string | City |
sessions.last.client.user_agent | string | Client browser user agent |
sessions.total | object | Total sessions |
Information about the computer¶
To get computer information from the Permanent Access section, use the agents/info
method
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
agent_id | number | Internal system agent ID |
Response:
{
"data": {
"id": 1001,
"name": "Allesandro Paci",
"group": "Accounting",
"disabled": false,
"limited": false,
"link_time": 1587837997,
"last_time": 1600374761,
"geo": {
"ip": "2.21.31.68",
"country": "USA",
"region": "California",
"city": "Los Angeles"
},
"permanent_url": "https://go.getscreen.me/paci",
"onetime_url": "https://go.getscreen.me/am2-l2g",
"preview_url": "https://getscreen.me/preview/1245273f5448a704379da46f476564a592efb17c6a7695adde96247cd7874416GbBzRm6SRLMqrP0YoYFMxCopL6NTzvn8.png",
"os": "win",
"version": "2.7.6",
"online": true,
"installed": true,
"favorite": false,
"owner": "john.smith@gmail.com",
"hardware": {
"BIOS": "ALASKA - 1072009 - F51 - American Megatrends - 5000E",
"BIOSDate": "",
"BIOSVersion": "20191218",
"CPU": "AMD Ryzen 5 2600X Six-Core Processor",
"CPUCores": 6,
"CPUCoresLogical": 12,
"CPUFamily": "AMD64 Family 23 Model 8 Stepping 2",
"CPUSpeed": 3600,
"ComputerDomain": "WORKGROUP",
"ComputerIP": [
"10.66.65.3",
"fe80::35da:bb0:c661:fff9"
],
"ComputerModel": "B450 AORUS ELITE",
"ComputerName": "DESKTOP-AU0VQEE",
"ComputerWorkgroup": "WORKGROUP",
"HDD": [ {
"Model": "INTEL SSDPEKNW512G8",
"Size": 488382
} ],
"Locale": "0419",
"LocaleCountry": "USA",
"LocaleCurrency": "USD",
"LocaleFormatDate": "MM-DD-YYYY",
"LocaleFormatTime": "H:mm:ss",
"LocaleOemPage": "437",
"LocaleTimezone": -420,
"LogicalDisks": [ {
"Disk": "C:",
"FileSystem": "NTFS",
"FreeSpace": 13668,
"Name": "",
"Size": 487757
} ],
"Monitors": [ {
"Name": "Universal PnP monitor",
"ScreenHeight": 1080,
"ScreenWidth": 1920
} ],
"NetAdapters": [ {
"Addresses": "",
"Cable": true,
"DCHP": "",
"DNS": "",
"MACAddress": "18:C0:4D:44:F0:61",
"Manufacturer": "Realtek",
"Name": "Realtek Gaming GbE Family Controller",
"Speed": 953,
"WoL": true
} ],
"OSName": "Microsoft Windows 10 Pro",
"OSVersion": "10.0.19044",
"RAMBanks": [ {
"Bank": "P0 CHANNEL A",
"Capacity": 8192,
"DataWidth": 64,
"Locator": "DIMM 0",
"Manufacturer": "Unknown",
"PartNumber": "F4-3200C16-8GSXFB",
"SerialNumber": "00000000"
} ],
"RAMPageFile": 51264,
"RAMPhys": 32716,
"RAMPhysAvail": 9380,
"RAMVirt": 134217727,
"RAMVirtAvail": 134213282,
"SoundDevices": [ {
"Name": "NVIDIA High Definition Audio"
} ],
"VideoCards": [ {
"Integrated": true,
"Name": "NVIDIA GeForce GT 710",
"RAM": 1024
} ],
"VideoName": "NVIDIA GeForce GT 710",
"VideoRAM": 1024
},
"sessions": {
"last": {
"id":148505,
"start_time":1600343858,
"stop_time":1600343900,
"client":{
"ip":"188.162.195.82",
"country":"Russian Federation",
"region":"Tatarstan",
"city":"Kazan",
"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
}
},
"total": 1
}
}
}
Response data:
Name | Type | Description |
---|---|---|
id | number | Internal system ID |
name | string | Name |
group | string | Group |
disabled | boolean | Is the agent blocked? |
limited | boolean | Is the agent limited? |
link_time | unixtime | Added to personal account date and time |
last_time | unixtime | Last active date and time |
geo | object | Location |
geo.ip | string | IP address |
geo.country | string | Country |
geo.region | string | Region |
geo.city | string | City |
permanent_url | string | Permanent connection URL |
onetime_url | string | URL for one-time connection |
preview_url | string | Desktop preview download URL |
os | string | Operating system. Possible values: win , mac , linux and android |
version | string | Agent version |
online | boolean | Current active state |
installed | boolean | Is the agent installed on the desktop? |
favorite | boolean | Is this a favorited desktop from the personal account? |
owner | string | Desktop access system owner account |
hardware | object | System information |
hardware.BIOS | string | BIOS information |
hardware.BIOSDate | string | Date of update |
hardware.BIOSVersion | string | Version |
hardware.CPU | string | CPU |
hardware.CPUCores | number | Number of cores |
hardware.CPUCoresLogical | number | Number of logical processors |
hardware.CPUFamily | string | Family |
hardware.CPUSpeed | number | Speed |
hardware.ComputerDomain | string | Domain |
hardware.ComputerIP | array | IP address |
hardware.ComputerModel | string | Model |
hardware.ComputerName | string | Computer name |
hardware.ComputerWorkgroup | string | Work group |
hardware.HDD | array | Hard drives |
hardware.HDD[].Model | string | Model |
hardware.HDD[].Size | number | Size |
hardware.Locale | string | Locale |
hardware.LocaleCountry | string | Country |
hardware.LocaleCurrency | string | Currency |
hardware.LocaleFormatDate | string | Date format |
hardware.LocaleFormatTime | string | Time format |
hardware.LocaleOemPage | string | Page charset |
hardware.LocaleTimezone | number | Time zone |
hardware.LogicalDisks | array | Logical drives |
hardware.LogicalDisks[].Disk | string | Label |
hardware.LogicalDisks[].FileSystem | string | File system type |
hardware.LogicalDisks[].FreeSpace | number | Free space (MB) |
hardware.LogicalDisks[].Name | string | Name |
hardware.LogicalDisks[].Size | number | Size (MB) |
hardware.Monitors | array | Monitors |
hardware.Monitors[].Name | string | Name |
hardware.Monitors[].ScreenHeight | number | Screen height |
hardware.Monitors[].ScreenWidth | number | Screen width |
hardware.NetAdapters | array | Network cards |
hardware.NetAdapters[].Addresses | string | Address |
hardware.NetAdapters[].Cable | boolean | Connecting to the Internet via LAN cable |
hardware.NetAdapters[].DCHP | string | DCHP |
hardware.NetAdapters[].DNS | string | DNS |
hardware.NetAdapters[].MACAddress | string | MAC address |
hardware.NetAdapters[].Manufacturer | string | Manufacturer |
hardware.NetAdapters[].Name | string | Name |
hardware.NetAdapters[].Speed | number | Speed |
hardware.NetAdapters[].WoL | boolean | Wake-on-LAN setting enabled |
hardware.OSName | string | Operating system name |
hardware.OSVersion | string | Operating system version |
hardware.RAMBanks | array | RAM |
hardware.RAMBanks[].Bank | string | Bank |
hardware.RAMBanks[].Capacity | number | Capacity |
hardware.RAMBanks[].Locator | string | Locator |
hardware.RAMBanks[].Manufacturer | string | Manufacturer |
hardware.RAMBanks[].PartNumber | string | Batch |
hardware.RAMBanks[].SerialNumber | string | Series |
hardware.SoundDevices | array | Sound cards |
hardware.SoundDevices[].Name | string | Name |
hardware.VideoCards | array | Video card |
hardware.VideoCards[].Integrated | boolean | Integrated |
hardware.VideoCards[].Name | string | Name |
hardware.VideoCards[].RAM | number | RAM |
sessions | object | Connection info |
sessions.last | object | Last connection |
sessions.last.id | number | Internal system connection ID |
sessions.last.start_time | unixtime | Connection start date and time |
sessions.last.stop_time | unixtime | Connection stop date and time |
sessions.last.client | object | Client info (connection creator) |
sessions.last.client.ip | string | IP address |
sessions.last.client.country | string | Country |
sessions.last.client.region | string | Region |
sessions.last.client.city | string | City |
sessions.last.client.user_agent | string | Client browser user agent |
sessions.total | object | Total sessions |
Change device property¶
To change some property of a device bound to your account, you can use the devices/update
method
You do not have to list all properties in the query. Only the ones you specify will be changed. See the parameters below for a list of fields available for updating.
Request:
POST https://api.getscreen.me/v1/agents/update
?apikey=<string>
BODY: {
"id": <number>,
"permanent_url": {
"enable": <boolean>,
"url": <string>,
"password": <string>
}
}
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
id | number | Internal system identifier of the agent |
permanent_url | object | Permanent link to connect |
permanent_url.enable | boolean | Enable/disable |
permanent_url.url | string | Link path |
permanent_url.password | string | Password for connection (at least 8 characters including letters and numbers) |
Response:
Response data:
Name | Type | Description |
---|---|---|
number | status | Result status. Possible values:
|
data | object | Modified data |
Get connection link¶
To connect to the desktop with API, you need to get a one-time link with the agents/connect
method
The link expires right after its first use. You need to get one each time you want to connect.
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
agent_id | number | Internal system agent ID |
device_id | number | The public identifier of the agent. Available in the agent's card in the personal account.agent_id parameter is not specified. |
video | bool | Manual control of video recording on/off (optional) |
Response:
{
"data":{
"url": "https://go.getscreen.me/john.smith/?connect=20177&llt=66b4kj671pm3abpp5xh17elpnpze245382m9pxbrx313l2xp52hmxqe4e1dekpej&s=c2c5ca25eb4fca787b74a97648e0856951e2b9c7aa02cbf83ac62c81e21a9bab"
}
}
Response data:
Name | Type | Description |
---|---|---|
url | string | Connection URL |
Request a wake-up call¶
To send a request to wake up a device using the Wake-on-LAN feature, you can use the agents/wake
request.
This feature requires preconfiguration of the device and its environment to work. Read more in the article How to configure Wake-on-LAN?.
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
id | number | Internal system identifier of the agent |
Response:
Response data:
Name | Type | Description |
---|---|---|
number | status | Result status. Possible values:
|
Logout of the account¶
To detach the device from your account and remove it from permanent access, use the agents/logout
method
Be careful! Once the device is detached, you will not be able to operate it.
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
id | number | Internal system agent ID |
Response:
Response data:
Name | Type | Description |
---|---|---|
number | status | Result status. Possible values:
|
Quick Support¶
Open connection list¶
To get a list of open connections from the Quick support section, use the support/list
method
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
Response:
{
"remain":100,
"data":[ {
"id":328,
"status":0,
"create_time":1600262268,
"invite_code":"408080316",
"invite_url":"https://go.getscreen.me/invite/408080316",
"connect_url":"https://go.getscreen.me/turbo/nrhaStVwQSQ1J4DW0cL4wc1ADUeyug8BZjFaCgEqT4wuFXSPXQrGoRRBUxK1uFTU1Sr7bYlsviZ0djTophpmnIhpaZuMfGSKdSefcDzOWCgJuGeHGA5hFkcflhAXhBrx",
"client_name":"Jacob Williams",
"client_os":"",
"client_preview_url":""
} ]
}
Name | Type | Description |
---|---|---|
id | number | Internal system connection ID |
status | number | Connection status. Possible values:
|
create_time | unixtime | Connection creation date and time |
invite_code | string | Invitation code |
invite_url | string | Invitation URL |
connect_url | string | Operator connection URL |
client_name | string | Client name |
client_os | string | Operating system. Possible values: win , mac , linux and android |
client_preview_url | string | Client desktop thumbnail |
Additional info:
Name | Type | Description |
---|---|---|
remain | number | Number of remaining connections within the rate plan |
Create connection¶
To create a scheduled connection for quick support, use the support/create
method
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
client_name | string | Client name (only visible to you). Optional parameter. |
Response:
{
"data":{
"id":328,
"status":0,
"create_time":1600262268,
"invite_code":"408080316",
"invite_url":"https://go.getscreen.me/invite/408080316",
"connect_url":"https://go.getscreen.me/turbo/nrhaStVwQSQ1J4DW0cL4wc1ADUeyug8BZjFaCgEqT4wuFXSPXQrGoRRBUxK1uFTU1Sr7bYlsviZ0djTophpmnIhpaZuMfGSKdSefcDzOWCgJuGeHGA5hFkcflhAXhBrx",
"client_name":"Jacob Williams",
"client_os":"",
"client_preview_url":""
}
}
Response data:
Name | Type | Description |
---|---|---|
id | number | Internal system connection ID |
status | number | Connection status. Possible values:
|
create_time | unixtime | Connection creation date and time |
invite_code | string | Invitation code |
invite_url | string | Invitation URL |
connect_url | string | Operator connection URL |
client_name | string | Client name |
client_os | string | Operating system. Possible values: win , mac , linux and android |
client_preview_url | string | Client desktop thumbnail |
Connection info¶
To get the info about a specific connection, use the support/info
method
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
connection_id | number * | Internal system connection ID |
Response:
{
"data":{
"id":328,
"status":2,
"create_time":1600262268,
"invite_code":"408080316",
"invite_url":"https://go.getscreen.me/invite/408080316",
"connect_url":"https://go.getscreen.me/turbo/nrhaStVwQSQ1J4DW0cL4wc1ADUeyug8BZjFaCgEqT4wuFXSPXQrGoRRBUxK1uFTU1Sr7bYlsviZ0djTophpmnIhpaZuMfGSKdSefcDzOWCgJuGeHGA5hFkcflhAXhBrx",
"client_name":"Jacob Williams",
"client_os":"win",
"client_preview_url":"https://getscreen.me/preview/f90d07668bccd418a5a8922f2ee455f1eb004c2bbeb5f9fe05ed6970c3389114Zl5PgknTWlU0fWBe4b9YoHNvRlD5Iwl5.png"
}
}
Response data:
Name | Type | Description |
---|---|---|
id | number | Internal system connection ID |
status | number | Connection status. Possible values:
|
create_time | unixtime | Connection creation date and time |
invite_code | string | Invitation code |
invite_url | string | Invitation URL |
connect_url | string | Operator connection URL |
client_name | string | Client name |
client_os | string | Operating system. Possible values: win , mac , linux and android |
client_preview_url | string | Client desktop thumbnail |
Close connection¶
To close a connection, use the support/close
method
Request:
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
connection_id | number * | Internal system connection ID |
Response:
The response will be returned empty. To analyze the command execution, use only HTTP response code.
Connections history¶
Get a connections list¶
To get a list of your connections, use the history/list
method
Request:
GET https://api.getscreen.me/v1/history/list
?apikey=<string>
&agent_id=<number>
&support_id=<number>
&date_from=<unixtime>
&date_to=<unixtime>
&video=<boolean>
&offset=<number>
&limit=<number>
Request parameters:
Parameter | Type | Value |
---|---|---|
apikey | string | Request authorization API key |
agent_id | string | Filter by agent ID |
support_id | number | Sort by Quick Support connection ID |
date_from | unixtime | Filter by date and time: period start |
date_to | unixtime | Filter by date and time: period end |
video | boolean | Filter by video recording |
offset | number | Offset for the first item in the list |
limit | number | Number of items in the list. Default value: 20 ; maximum value: 100 |
Response:
{
"offset": 0,
"limit": 10,
"total": 15,
"filter": {
"date_from": 1608660281,
"date_to": 1608660389,
"agent_id": 1001,
"support_id": 1002,
"video": true
},
"data": [ {
"id": 27233,
"start": 1608660273,
"stop": 1608660281,
"support_id": 1002,
"clients": [ {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
"login": "john.smith@gmail.com",
"geo": {
"ip": "2.21.31.68",
"country": "USA",
"region": "California",
"city": "Los Angeles"
}
} ],
"agent": {
"id": 1001,
"name": "DESKTOP-SJBU5PO",
"group": "Accounting",
"geo": {
"ip": "2.21.31.68",
"country": "USA",
"region": "California",
"city": "Los Angeles"
},
"os": "win",
"version": "2.1.5",
"owner": "john.smith@gmail.com"
},
"video": {
"url": "https://st1.getscreen.me/video/2/27233.mp4",
"size": 428652
}
}, ... ]
}
Response data:
Name | Type | Description |
---|---|---|
id | number | Internal system connection ID |
start | unixtime | Connection start date and time |
stop | unixtime | Connection end date and time |
support_id | number | Quick Support connection ID |
clients | array | List of clients who joined the connection |
clients[].user_agent | string | User agent |
clients[].login | string | User login |
clients[].geo | object | Location |
clients[].geo.ip | string | IP address |
clients[].geo.country | string | Country |
clients[].geo.region | string | Region |
clients[].geo.city | string | City |
agent | object | Agent info |
agent.id | number | Internal system agent ID |
agent.name | string | Name |
agent.group | string | Group |
agent.geo | object | Location |
agent.geo.ip | string | IP address |
agent.geo.country | string | Country |
agent.geo.region | string | Region |
agent.geo.city | string | City |
agent.os | string | Operating system. Possible values: win , mac , linux or android |
agent.version | string | Software version |
agent.owner | string | Account login of the permanent access owner |
video | object | Video recording info |
video.url | string | Video recording file address?apikey= parameter with your API key. |
video.size | number | Video recording file size in bytes |
Last update: January 6th, 2025