Grids
Organize dedicated compute into grids for your applications.
Grids belong to organizations. Organization-level calls take ?org=; grid-ID calls resolve it from the grid. Admins create and manage grids; Developers deploy to accessible grids and Viewers inspect them. Per-person quota policies are configured in the portal, not through the public API.
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 slugs403
key_project_restricted: The key is limited to specific projects, and this acts on the organization
An API key from Account settings, e.g. kn_...
Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one
Items per page, 1 to 200 (default 50)
nextCursor from the previous page; omit for the first page
OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
GET /v1/grids HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"grids": [
{
"id": "text",
"name": "text",
"org": {
"slug": "text",
"name": "text"
},
"access": {
"role": "admin",
"outside": true,
"isCreator": true
},
"visibility": "private",
"createdBy": {
"userId": "text",
"name": null,
"email": "text"
},
"nodes": [
"text"
],
"autoCreated": true,
"priorityMode": "absolute",
"needsReconciliation": true,
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
]
}
],
"nextCursor": null
}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 slugs403
key_project_restricted: The key is limited to specific projects, and this acts on the organization
An API key from Account settings, e.g. kn_...
Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one
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.
^\S+$Grid name
Who in the organization can see and deploy to it; private by default
Addresses of servers to attach
Created
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/grids HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 155
{
"name": "text",
"visibility": "private",
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
],
"nodes": [
"text"
]
}{
"id": "text",
"name": "text",
"org": {
"slug": "text",
"name": "text"
},
"access": {
"role": "admin",
"outside": true,
"isCreator": true
},
"visibility": "private",
"createdBy": {
"userId": "text",
"name": null,
"email": "text"
},
"nodes": [
"text"
],
"autoCreated": true,
"priorityMode": "absolute",
"needsReconciliation": true,
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
],
"warning": null
}Requires pools:read (View grids and servers).
An API key from Account settings, e.g. kn_...
Grid id
OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
GET /v1/grids/{gridId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"name": "text",
"org": {
"slug": "text",
"name": "text"
},
"access": {
"role": "admin",
"outside": true,
"isCreator": true
},
"visibility": "private",
"createdBy": {
"userId": "text",
"name": null,
"email": "text"
},
"nodes": [
"text"
],
"autoCreated": true,
"priorityMode": "absolute",
"needsReconciliation": true,
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
]
}Change a grid's settings, visibility, membership or priority mode (admins). Membership changes are explicit lists of servers to add and to remove.
Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).
An API key from Account settings, e.g. kn_...
Grid id
Grid name
private: admins, its creator and the people added; org: everyone in the organization
Servers to add to the grid
Servers to remove from the grid
How app priorities apply when the grid is contended
OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
PATCH /v1/grids/{gridId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 207
{
"name": "text",
"visibility": "private",
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
],
"addNodes": [
"text"
],
"removeNodes": [
"text"
],
"priorityMode": "absolute"
}{
"id": "text",
"name": "text",
"org": {
"slug": "text",
"name": "text"
},
"access": {
"role": "admin",
"outside": true,
"isCreator": true
},
"visibility": "private",
"createdBy": {
"userId": "text",
"name": null,
"email": "text"
},
"nodes": [
"text"
],
"autoCreated": true,
"priorityMode": "absolute",
"needsReconciliation": true,
"volumes": [
{
"mountPath": "text",
"maxSize": 1,
"tag": "text"
}
],
"networks": [
{
"cidr": "text",
"tag": "text"
}
]
}Requires pools:admin (Delete grids and manage who they are shared with).
An API key from Account settings, e.g. kn_...
Grid id
OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
DELETE /v1/grids/{gridId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"deleted": true
}Set a grid member's scheduling priority, -100 to 100. Higher wins when the grid is contended; -100 means backup only. Admins of the grid's organization.
Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).
An API key from Account settings, e.g. kn_...
Grid id
Server address; must be a member of the grid
^0x[0-9a-fA-F]{40}$-100 (backup only) to 100
OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
PATCH /v1/grids/{gridId}/servers/{address} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14
{
"priority": 1
}{
"gridId": "text",
"address": "text",
"priority": 1
}Start an app that targets the grid, as an admin of the grid's organization, without a role on the app itself. The app's creator is notified and its organization is billed for it.
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:
403
forbidden: The backend refused the action for this grid role409
app_not_on_grid: The app does not target (or run on) this grid
An API key from Account settings, e.g. kn_...
Grid id
Runtime identifier of the app (guid on list_apps, get_server)
Shown to the app's creator in their notification
Accepted
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/grids/{gridId}/apps/{appGuid}/start HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"reason": "text"
}{
"gridId": "text",
"appGuid": "text",
"appId": null,
"appName": null
}Stop an app running on the grid, as an admin of the grid's organization, without a role on the app itself. The app's creator is notified.
Requires pools:write (Edit grids, manage their servers, attach machines, set Smart Lifecycle and SSH keys).
Errors specific to this operation:
403
forbidden: The backend refused the action for this grid role409
app_not_on_grid: The app does not target (or run on) this grid
An API key from Account settings, e.g. kn_...
Grid id
Runtime identifier of the app (guid on list_apps, get_server)
Shown to the app's creator in their notification
Accepted
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/grids/{gridId}/apps/{appGuid}/stop HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"reason": "text"
}{
"gridId": "text",
"appGuid": "text",
"appId": null,
"appName": null
}Was this helpful?