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

All parameters are optional. Combine as many as you need and they are all applied together.

Key Data Type Required Notes
hostname string optional 1–255 characters. Matches any server whose hostname contains this value.
external_ip string optional Up to 45 characters, made up of hexadecimal digits, dots and colons. Matches any server whose external IP starts with this value, so 203.0.113. matches the whole range.
statuses array of string optional One or more of Connected, Syncing, Warning, Upgrading, Disconnected. Case-insensitive.
providers array of string optional One or more provider names, 1–255 characters each. Use __not_set__ to match servers that have no provider recorded.
locations array of string optional One or more locations, 1–255 characters each. Use __not_set__ to match servers that have no location recorded.
os_release_names array of string optional One or more operating system release names, 1–255 characters each. For example Debian GNU/Linux or Ubuntu.
agent_versions array of string optional One or more Keystash Agent versions, 1–255 characters each.
server_group_ids array of string optional One or more Server Group id values, being the server_group_id field in a response and the id that a Server Groups call returns. Each is 1–16 alphanumeric characters.
start_date string optional Inclusive lower bound on the server's created date, in UTC YYYY-MM-DD HH:mm:ss. Must be supplied with end_date and must not be later than it.
end_date string optional Inclusive upper bound on the server's created date, in UTC YYYY-MM-DD HH:mm:ss. Must be supplied with start_date.
limit integer optional Rows to return. Defaults to 250, which is also the maximum; a larger value is reduced to 250.
offset integer optional Row offset for paging. Defaults to 0.

Note

A parameter that is not recognised, or a value that fails its rule, returns a 400 BadArgument naming every parameter at fault. See Filtering Lists for the full rules, and Paging Through Lists for the X-Total-Count, X-Limit and X-Offset headers.

Request Body

None.

Response Fields

A successful response is a JSON array of server objects, returned in hostname order.

Example Request

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

Narrowing the list to the servers of one provider that are up or need attention, 100 rows at a time:

curl --location --request GET 'https://app.keystash.io/api/v1/servers/list?statuses[]=Connected&statuses[]=Warning&providers[]=DigitalBitsHosting&limit=100' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Total-Count: 2
X-Limit: 250
X-Offset: 0

[
  {
    "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

Invalid Filter Value (400 Bad Request)

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

{
  "error": {
    "code": "BadArgument",
    "message": "One or more query parameters were invalid.",
    "details": [
      {
        "field": "statuses",
        "message": "Unrecognised status label. Supply one or more of the allowed values.",
        "received": "Banana",
        "allowed_values": ["Connected", "Syncing", "Warning", "Upgrading", "Disconnected"]
      }
    ]
  }
}

Unknown Query Parameter (400 Bad Request)

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

{
  "error": {
    "code": "BadArgument",
    "message": "One or more query parameters were invalid.",
    "details": [
      {
        "field": "provider",
        "message": "Unknown query parameter. Did you mean 'providers'?",
        "received": "Linode",
        "allowed_values": [
          "hostname",
          "external_ip",
          "statuses",
          "providers",
          "locations",
          "os_release_names",
          "agent_versions",
          "server_group_ids",
          "start_date",
          "end_date",
          "limit",
          "offset"
        ]
      }
    ]
  }
}

Missing Permission (403 Forbidden)

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 '3nfpkLHFYblvgnp8' 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": []
  }
}