Ctrlk
APIMCPOpen portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Servers

Provision servers, follow orders and manage machine lifecycles.

Pass the organization slug as ?org= where listed in the operation parameters. Admins manage servers, orders and SSH keys; other members can inspect accessible infrastructure. Use name as the display label and address as the stable identifier.

List the organization's servers, those it rents, and pending orders. A shared grid's servers count as usable

get

Requires pools:read (View grids and servers).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

limitinteger · min: 1 · max: 200Optional

Items per page, 1 to 200 (default 50)

cursorstring · min: 1 · max: 512Optional

nextCursor from the previous page; omit for the first page

Responses
200

OK

application/json
get/servers
GET /v1/servers HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "servers": [
    {
      "address": "text",
      "name": null,
      "hostname": null,
      "csp": null,
      "region": null,
      "zone": null,
      "instanceType": null,
      "kcRegion": null,
      "owned": true,
      "ownerName": null,
      "state": "text",
      "hibernation": "text",
      "lastPulseAt": "2026-01-01T00:00:00.000Z",
      "specs": {
        "cpuThreads": 1,
        "ramBytes": 1,
        "storageBytes": 1,
        "gpus": [
          {
            "model": "text",
            "count": 1,
            "vramBytes": 1
          }
        ]
      },
      "utilization": {
        "cpu": 1,
        "ram": 1,
        "storage": 1,
        "gpu": 1,
        "vram": 1
      },
      "runningApps": 1,
      "lease": {
        "id": "text",
        "gridId": "text",
        "availableUntil": "2026-01-01T00:00:00.000Z",
        "priceCentsPerHour": 1
      },
      "provisionStatus": null,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null,
  "pending": [
    {
      "orderId": "text",
      "address": null,
      "status": "text",
      "failure": null,
      "csp": null,
      "region": null,
      "instanceType": null,
      "gridIds": [
        "text"
      ],
      "attempts": {
        "made": 1,
        "max": 1
      },
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Order dedicated servers from a cloud provider. Checks the quota and the balance first; set dryRun to get the cost estimate without ordering. Poll servers.orders.get with the returned order id to follow the order.

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 402 insufficient_balance: The balance does not cover the minimum runtime of the order; topUpNeededCents says how much to add (billingUrl)

  • 403 provision_quota: The organization's provisioning limit is reached

  • 400 no_provider_for_region: No provider serves the requested Kinesis region

  • 400 ephemeral_ssd_unavailable: The instance type has no bundled local SSD; set storageSizeGb instead

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Header parameters
Idempotency-Keystring · min: 1 · max: 255Optional

Any unique string of at most 255 characters. A retry with the same key and body returns the first call's response (with Idempotent-Replayed: true) instead of acting twice; a different body is refused with 409 idempotency_conflict, and a retry while the first call is still running gets 409 request_in_progress. Keys are kept for 24 hours.

Pattern: ^\S+$
Body
cspstring · enumRequired

Cloud provider

Possible values:
regionstring · min: 1Required

Provider region id (see catalog.regions)

zonestring · min: 1Optional

Availability zone; omit to let the provider choose

instanceTypestring · min: 1Required

Instance type id (see catalog.instanceTypes)

countinteger · min: 1 · max: 10Optional

Servers to order, 1 to 10 (default 1)

storageSizeGbinteger · min: 50 · max: 10000Optional

Disk per server in GB, 50 to 10000; required unless useEphemeralSsd is set

useEphemeralSsdbooleanOptional

Use the bundled local SSD instead of a network volume (supported non-hibernatable Kinesis compute configurations only)

gridIdsstring[] · max: 10Optional

Grids the servers join once they register

dryRunbooleanOptional

Run every check and return the estimate without ordering

Responses
200

OK

application/json
post/servers/provision
POST /v1/servers/provision HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 153

{
  "csp": "kinesis",
  "region": "text",
  "zone": "text",
  "instanceType": "text",
  "count": 1,
  "storageSizeGb": 1,
  "useEphemeralSsd": true,
  "gridIds": [
    "text"
  ],
  "dryRun": true
}
{
  "dryRun": true,
  "csp": "text",
  "region": "text",
  "instanceType": "text",
  "count": 1,
  "estimate": {
    "instanceCount": 1,
    "totalHourlyCostCents": 1,
    "totalRequiredCents": 1,
    "minimumHours": 1,
    "balanceCents": 1,
    "overLimitCents": 1,
    "availableRunwayCents": 1,
    "topUpNeededCents": 1
  },
  "orders": [
    {
      "orderId": "text",
      "status": "text",
      "count": 1,
      "csp": null,
      "failure": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "dismissed": true
    }
  ]
}

Destroy dedicated servers. They leave every grid first. Irreversible.

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
post/servers/deprovision
POST /v1/servers/deprovision HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}
{
  "results": [
    {
      "address": "text",
      "ok": true,
      "error": null
    }
  ]
}

Hibernate servers: the machine stops and stops billing compute, its disk is kept

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
post/servers/hibernate
POST /v1/servers/hibernate HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}
{
  "results": [
    {
      "address": "text",
      "ok": true,
      "error": null,
      "reason": "out_of_stock"
    }
  ]
}

Wake hibernated servers. Fails with out_of_stock when the provider has no capacity.

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
post/servers/wake
POST /v1/servers/wake HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}
{
  "results": [
    {
      "address": "text",
      "ok": true,
      "error": null,
      "reason": "out_of_stock"
    }
  ]
}

Reboot dedicated servers

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
post/servers/reboot
POST /v1/servers/reboot HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}
{
  "results": [
    {
      "address": "text",
      "ok": true,
      "error": null
    }
  ]
}

Get a provisioning order the caller placed and the machines it has produced. Completed, replacement and dismissed orders are readable too. Poll this after servers.provision or servers.replace until done.

get

Requires pools:read (View grids and servers).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
orderIdstring · min: 1Required

Provisioning order id

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
get/servers/orders/{orderId}
GET /v1/servers/orders/{orderId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "order": {
    "orderId": "text",
    "status": "text",
    "count": 1,
    "csp": null,
    "failure": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "dismissed": true
  },
  "instances": [
    {
      "orderId": "text",
      "address": null,
      "status": "text",
      "failure": null,
      "csp": null,
      "region": null,
      "instanceType": null,
      "gridIds": [
        "text"
      ],
      "attempts": {
        "made": 1,
        "max": 1
      },
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "done": true
}

Retry a failed provisioning order

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 409 provision_order_failed: The backend refused the action for this order; the message says why

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
orderIdstring · min: 1Required

Provisioning order id

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
post/servers/orders/{orderId}/retry
POST /v1/servers/orders/{orderId}/retry HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "order": {
    "orderId": "text",
    "status": "text",
    "count": 1,
    "csp": null,
    "failure": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "dismissed": true
  }
}

Cancel an in-flight provisioning order, or hide a finished one from the pending list

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 409 provision_order_failed: The backend refused the action for this order; the message says why

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
orderIdstring · min: 1Required

Provisioning order id

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
post/servers/orders/{orderId}/dismiss
POST /v1/servers/orders/{orderId}/dismiss HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "orderId": "text",
  "dismissed": true
}

Get a provision token and install command for attaching a machine. The one-line command attaches it (bring your own device) as one of the organization's servers. The same usable token comes back on repeated calls until it is consumed or expires; forceNew mints a fresh one.

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
expiresInSecinteger · min: 60 · max: 604800Optional

Lifetime of a newly minted token, 3600 by default

forceNewbooleanOptional

Mint a new token even when a usable one exists

Responses
200

OK

application/json
post/servers/byod-token
POST /v1/servers/byod-token HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "expiresInSec": 1,
  "forceNew": true
}
{
  "token": "text",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "needVpn": true,
  "expiresInSec": 1,
  "installCommand": "text"
}

The Smart Lifecycle setting of each server the organization owns. On, the platform hibernates it when nothing runs on it (storage billing only) and wakes it when an app needs it

get

Requires pools:read (View grids and servers).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
get/servers/smart-lifecycle
GET /v1/servers/smart-lifecycle HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "servers": [
    {
      "address": "text",
      "enabled": true
    }
  ]
}

Turn automatic hibernate and wake-up (Smart Lifecycle) on or off. For the org's servers

patch

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

enabledbooleanRequired

On or off

Responses
200

OK

application/json
patch/servers/smart-lifecycle
PATCH /v1/servers/smart-lifecycle HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "addresses": [
    "text"
  ],
  "enabled": true
}
{
  "servers": [
    {
      "address": "text",
      "enabled": true
    }
  ]
}

Get one server: specs, utilization, apps, grids and provisioning order. Its own organization also sees its public address

get

Requires pools:read (View grids and servers).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
addressstringRequired

Server address

Pattern: ^0x[0-9a-fA-F]{40}$
Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
get/servers/{address}
GET /v1/servers/{address} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "address": "text",
  "name": null,
  "hostname": null,
  "csp": null,
  "region": null,
  "zone": null,
  "instanceType": null,
  "kcRegion": null,
  "owned": true,
  "ownerName": null,
  "state": "text",
  "hibernation": "text",
  "lastPulseAt": "2026-01-01T00:00:00.000Z",
  "specs": {
    "cpuThreads": 1,
    "ramBytes": 1,
    "storageBytes": 1,
    "gpus": [
      {
        "model": "text",
        "count": 1,
        "vramBytes": 1
      }
    ]
  },
  "utilization": {
    "cpu": 1,
    "ram": 1,
    "storage": 1,
    "gpu": 1,
    "vram": 1
  },
  "runningApps": 1,
  "lease": {
    "id": "text",
    "gridId": "text",
    "availableUntil": "2026-01-01T00:00:00.000Z",
    "priceCentsPerHour": 1
  },
  "provisionStatus": null,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "ipAddress": null,
  "version": null,
  "countryCode": null,
  "autoWakeup": true,
  "gridIds": [
    "text"
  ],
  "apps": [
    {
      "guid": "text",
      "image": null,
      "state": "text",
      "targetState": "running",
      "reportedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "order": {
    "id": "text",
    "status": "text",
    "failure": null,
    "attempts": {
      "made": 1,
      "max": 1
    },
    "awaitingStockSince": "2026-01-01T00:00:00.000Z"
  }
}

Read the newest lines of a server's own logs. Agent, runtime health, installation and GPU setup, for one of the organization's servers. Narrow the window with since and until; lines come back oldest to newest.

get

Requires monitoring:read (Read usage metrics, app logs, build logs and server logs).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
addressstringRequired

Server address

Pattern: ^0x[0-9a-fA-F]{40}$
Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

sincestring · date-timeOptional

Earliest line to include; omit for no lower bound

untilstring · date-timeOptional

Latest line to include; omit for now

limitinteger · min: 1 · max: 5000Optional

Newest lines to return within the window, 500 by default

Responses
200

OK

application/json
get/servers/{address}/logs
GET /v1/servers/{address}/logs HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "logs": [
    {
      "at": "2026-01-01T00:00:00.000Z",
      "source": "text",
      "level": "trace",
      "text": "text"
    }
  ],
  "truncated": true
}

The organization's SSH public keys and where each is installed (admins). Also its servers a key can be installed on (those added without Kinesis Remote Reach)

get

Requires pools:read (View grids and servers).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
get/ssh-keys
GET /v1/ssh-keys HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "keys": [
    {
      "id": "text",
      "label": "text",
      "fingerprint": "text",
      "servers": [
        "text"
      ],
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "eligibleServers": [
    {
      "address": "text",
      "csp": null,
      "region": null,
      "instanceType": null,
      "ipAddress": null
    }
  ]
}

Register an SSH public key under a label. OpenSSH format; assign it to servers afterwards

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
labelstring · min: 1 · max: 64Required

A name for the key

publicKeystring · min: 1 · max: 16384Required

The public key, e.g. the contents of id_ed25519.pub

Responses
201

Created

application/json
post/ssh-keys
POST /v1/ssh-keys HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "label": "text",
  "publicKey": "text"
}
{
  "id": "text",
  "label": "text",
  "fingerprint": "text",
  "servers": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Delete an SSH key; it is removed from every server it was installed on

delete

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
keyIdstring · min: 1Required

Key id from the list

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Responses
200

OK

application/json
delete/ssh-keys/{keyId}
DELETE /v1/ssh-keys/{keyId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "deleted": true
}

Install an SSH key on servers (eligibleServers in sshKeys.list); ssh <user>@<ipAddress> then works with the matching private key

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
keyIdstring · min: 1Required

Key id from the list

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Body
addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
post/ssh-keys/{keyId}/servers
POST /v1/ssh-keys/{keyId}/servers HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}
{
  "id": "text",
  "label": "text",
  "fingerprint": "text",
  "servers": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Remove an SSH key from servers

delete

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
keyIdstring · min: 1Required

Key id from the list

Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

addressesstring[] · min: 1 · max: 50Required

Server addresses, at most 50

Responses
200

OK

application/json
delete/ssh-keys/{keyId}/servers
DELETE /v1/ssh-keys/{keyId}/servers?addresses=text HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "label": "text",
  "fingerprint": "text",
  "servers": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Provision an identical server and retire this one once the new one is up. The retired server's disk is not kept. Poll servers.orders.get with the returned order id to follow the replacement.

post

Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 400 org_required: The caller reaches more than one organization and named none; details.orgs lists their slugs

  • 403 key_project_restricted: The key is limited to specific projects, and this acts on the organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
addressstringRequired

Address of the server to replace

Pattern: ^0x[0-9a-fA-F]{40}$
Query parameters
orgstring · min: 3 · max: 39Optional

Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Header parameters
Idempotency-Keystring · min: 1 · max: 255Optional

Any unique string of at most 255 characters. A retry with the same key and body returns the first call's response (with Idempotent-Replayed: true) instead of acting twice; a different body is refused with 409 idempotency_conflict, and a retry while the first call is still running gets 409 request_in_progress. Keys are kept for 24 hours.

Pattern: ^\S+$
Responses
202

Accepted

application/json
post/servers/{address}/replace
POST /v1/servers/{address}/replace HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "order": {
    "orderId": "text",
    "status": "text",
    "count": 1,
    "csp": null,
    "failure": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "dismissed": true
  }
}
PreviousGrids
NextCatalog

Was this helpful?