Skip to content

Servers

The Servers resource provides access to all methods relating to Servers in Keystash.

List Servers

Path: /servers/list

Method: GET

Authentication: Bearer Token

Request Headers

Key Value Required
Accept-Encoding gzip optional

Request Parameters

None.

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/servers/list' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "DmcEgixUXpWVv7tk",
    "hostname": "my-prod-host.hostingprovider.net",
    "description": "Prod Host 1",
    "server_group_id": "BD720EP87kNORRcH",
    "server_group_name": "Production Servers",
    "external_ip": "169.8.8.45",
    "internal_ip": "192.168.2.59, 192.168.122.1, 172.17.0.1, 172.27.0.1, 172.24.0.1, 172.18.0.1, 172.19.0.1, 100.115.147.29, 169.254.0.2, ::1, fe80::6742:801:812b:7096, fe80::42:90ff:fe30:f32e, fe80::42:2dff:fe65:89c5, fe80::42:daff:fe6d:6f31, fe80::c483:4bff:fee1:7f3a, fe80::7855:70ff:fe90:169a, fe80::70a9:deff:fe12:15ad",
    "location": "London, United Kingdom",
    "provider": "DigitalBitsHosting",
    "status": "Connected",
    "status_message": "",
    "agent_version": "1.4.25",
    "architecture": "x64",
    "os_release_name": "Debian GNU/Linux",
    "os_release_version": "12 (bookworm)",
    "cpu_cores": 2,
    "memory": 3658,
    "upgrade_available": true,
    "created": "2023-11-14 16:53:55",
    "modified": "2023-11-14 16:53:56"
  },
  {
    "id": "p8CduXmyw6n9dzdd",
    "hostname": "my-prod-arm64-host.hostingprovider.net",
    "description": "Ubuntu ARM64 host",
    "server_group_id": "BD720EP87kNORRcH",
    "server_group_name": "Production Servers",
    "external_ip": "169.8.8.46",
    "internal_ip": "192.168.1.71",
    "location": "London, United Kingdom",
    "provider": "DigitalBitsHosting",
    "status": "Disconnected",
    "status_message": "This server has not been seen in the last 5min.",
    "agent_version": "1.5.0",
    "architecture": "arm64",
    "os_release_name": "Ubuntu",
    "os_release_version": "22.04.3 LTS (Jammy Jellyfish)",
    "cpu_cores": 4,
    "memory": 3658,
    "upgrade_available": false,
    "created": "2024-02-20 17:46:57",
    "modified": "2024-02-20 17:46:59"
  }
]

Example Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "Forbidden",
    "message": "You do not have the required permission to access this path.",
    "details": [
      {
        "path": "/api/v1/servers/list"
      }
    ]
  }
}

View Server

Path: /servers/view

Method: GET

Authentication: Bearer Token

Request Headers

Key Value Required
Accept-Encoding gzip optional

Request Parameters

Key Data Type Required Notes
id string required The ID of the server to view

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/servers/view?id=DmcEgixUXpWVv7tk' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "DmcEgixUXpWVv7tk",
  "hostname": "my-prod-host.hostingprovider.net",
  "description": "Prod Host 1",
  "server_group_id": "BD720EP87kNORRcH",
  "server_group_name": "Production Servers",
  "external_ip": "169.8.8.45",
  "internal_ip": "192.168.2.59, 192.168.122.1, 172.17.0.1, 172.27.0.1, 172.24.0.1, 172.18.0.1, 172.19.0.1, 100.115.147.29, 169.254.0.2, ::1, fe80::6742:801:812b:7096, fe80::42:90ff:fe30:f32e, fe80::42:2dff:fe65:89c5, fe80::42:daff:fe6d:6f31, fe80::c483:4bff:fee1:7f3a, fe80::7855:70ff:fe90:169a, fe80::70a9:deff:fe12:15ad",
  "location": "London, United Kingdom",
  "provider": "DigitalBitsHosting",
  "status": "Connected",
  "status_message": "",
  "agent_version": "1.4.25",
  "architecture": "x64",
  "os_release_name": "Debian GNU/Linux",
  "os_release_version": "12 (bookworm)",
  "cpu_cores": 2,
  "memory": 3658,
  "upgrade_available": true,
  "created": "2023-11-14 16:53:55",
  "modified": "2023-11-14 16:53:56"
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Deploy Server Command

Path: /servers/deploy-server-command

Method: GET

Authentication: Bearer Token

Request Headers

Key Value Required
Accept-Encoding gzip optional

Request Parameters

Key Data Type Required Notes
operating_system string required Specifies the operating system for the server. The available options are: almalinux_8, almalinux_9, almalinux_10, amazonlinux_2, amazonlinux_2023, centos_7, centos_8, centos_9, centos_10, debian_10, debian_11, debian_12, debian_13, fedora_server_34, fedora_server_35, fedora_server_36, fedora_server_37, fedora_server_38, fedora_server_39, fedora_server_40, fedora_server_41, fedora_server_42, oraclelinux_7, oraclelinux_8, oraclelinux_9, oraclelinux_10, rhel_7, rhel_8, rhel_9, rhel_10, rockylinux_8, rockylinux_9, rockylinux_10, ubuntu_18, ubuntu_20, ubuntu_21, ubuntu_22, ubuntu_23, ubuntu_24, ubuntu_25
deployment_secret_id string required The deployment secret ID to use for the server deployment
server_group_id string required The server group ID to deploy the server to
proxy_server string optional The proxy server to use for the deployment. Example: "https://my-proxy.example.com:8443"

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/servers/deploy-server-command?operating_system=rhel_10&deployment_secret_id=H6LPlSC081GIqzW0&server_group_id=DmcEgixUXpWVv7tk' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "individual_commands": {
    "install": [
      "dnf install -y https://qa-download.keystash.io/keystash-repo-1.0-1.noarch.rpm",
      "dnf install -y keystash"
    ],
    "configuration": [
      "/opt/keystash/keystash-key-manager.bin --mode=config yNs8vQmT5z1HGn3Q CKnmk_crFvNZixAMIV-mlbVyzgIkYqwhpJKe G3PqRjmcBvave0BG"
    ],
    "service": [
      "systemctl start keystash",
      "systemctl enable keystash"
    ]
  },
  "raw_command": "dnf install -y https://qa-download.keystash.io/keystash-repo-1.0-1.noarch.rpm\ndnf install -y keystash\n/opt/keystash/keystash-key-manager.bin --mode=config yNs8vQmT5z1HGn3Q CKnmk_crFvNZixAMIV-mlbVyzgIkYqwhpJKe G3PqRjmcBvave0BG\nsystemctl start keystash\nsystemctl enable keystash"
}

Example Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "There was missing argument in your request. Please check your request and resubmit.",
    "details": [
      "Deployment Secret not found."
    ]
  }
}

Update Server

Path: /servers/update

Method: PATCH

Authentication: Bearer Token

Request Headers

Key Value Required
Content-Type application/json required

Request Parameters

None.

Request Body Parameters

Key Data Type Required Notes
id string required The ID of the server to update
description string optional New description for the server
server_group_id string optional ID of the new server group

Example Request Body

{
  "id": "3nfpkLHFYblvgnp8",
  "description": "Updated via API",
  "server_group_id": "Ejh15L6CEcDNDKri"
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/servers/update' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "3nfpkLHFYblvgnp8",
    "description": "Updated via API",
    "server_group_id": "Ejh15L6CEcDNDKri"
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server with ID 'nJvWmR2CoeQJ3IDO' was successfully updated."
}

Example Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "The Server Group could not be found or there was a problem selecting the Server Group.",
    "details": ["Please check your server_group_id field."]
  }
}

Delete Server

Path: /servers/delete

Method: DELETE

Authentication: Bearer Token

Request Headers

Key Value Required
Accept-Encoding gzip optional

Request Parameters

Key Data Type Required Notes
id string required The ID of the server to delete

Request Body

None.

Example Request

curl --location --request DELETE 'https://app.keystash.io/api/v1/servers/delete?id=DmcEgixUXpWVv7tk' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server with ID 'DmcEgixUXpWVv7tk' was successfully deleted."
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem retrieving the Server from the Database or the Server by the provided ID was not found.",
    "details": []
  }
}