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

Apps

Deploy, configure and operate container applications.

Apps follow their project’s organization and visibility. Resource paths identify the organization; GET /apps can filter by org. Developers operate apps they can edit. Admins or the app’s creator delete or move it; moves stay within an organization. Grid quotas count against the app’s creator, and serverless settings still apply.

Check which servers could run an app that does not exist yet, from the placement-relevant parts of its configuration, before create_app. Nothing is created.

post

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project the app would be created in

Pattern: ^[0-9a-fA-F]{24}$
Body
Responses
200

OK

application/json
post/projects/{projectId}/placement
POST /v1/projects/{projectId}/placement HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 458

{
  "config": {
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": "amd",
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "us-west"
      ],
      "providers": [
        {
          "csp": "aws",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ]
  }
}
{
  "placeable": true,
  "serversWithCapacity": 1,
  "serversWithoutCapacity": 1,
  "wakeable": 1,
  "wakeableAwaitingStock": 1,
  "provisionable": true,
  "rejections": [
    {
      "server": "text",
      "reason": "text"
    }
  ]
}

List the apps the caller can see, oldest first. Across every project, or within one

get

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

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

Slug of an organization (see orgs.list) to list only what is in it or shared into it

projectIdstringOptional

Limit the list to one project

Pattern: ^[0-9a-fA-F]{24}$
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/apps
GET /v1/apps HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apps": [
    {
      "id": "text",
      "projectId": "text",
      "name": "text",
      "guid": "text",
      "source": null,
      "image": null,
      "domain": null,
      "buildState": null,
      "access": {
        "role": "admin",
        "outside": true,
        "isCreator": true
      },
      "createdBy": {
        "userId": "text",
        "name": null,
        "email": "text"
      },
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}

List the apps in a project

get

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Limit the list to one project

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

Slug of an organization (see orgs.list) to list only what is in it or shared into it

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/projects/{projectId}/apps
GET /v1/projects/{projectId}/apps HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apps": [
    {
      "id": "text",
      "projectId": "text",
      "name": "text",
      "guid": "text",
      "source": null,
      "image": null,
      "domain": null,
      "buildState": null,
      "access": {
        "role": "admin",
        "outside": true,
        "isCreator": true
      },
      "createdBy": {
        "userId": "text",
        "name": null,
        "email": "text"
      },
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Create an app from a container image, or from a GitHub repository with source, and start it. With envFrom the new app takes another app's environment variables, secret values included, copied on the server. Omitted config fields take the dashboard defaults (1 GiB RAM, 1 GB disk, 1 to 3 instances, no GPU).

post

Requires apps:write (Create, update, start, stop, restart and rebuild apps), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 402 balance_over_limit: The organization's balance is below the allowed negative limit; add credits and retry

  • 429 app_creation_quota_exceeded: The organization's app creation quota is used up; add a payment method or wait for the window

  • 400 no_suitable_machines: No machine can run this configuration; lower the hardware requirements or ask for provisioning

  • 429 grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas

  • 403 serverless_disabled: The app would run on Kinesis serverless capacity, which the organization keeps to its admins; target a grid

  • 503 github_not_configured: GitHub deployments are not enabled on this server

  • 404 github_installation_not_found: The caller has no connected GitHub account with this installation id; connect it in the dashboard

  • 404 github_repo_not_found: The installation cannot see the repository; grant the GitHub App access to it

  • 502 upstream_github: GitHub did not answer; retry shortly

  • 404 github_branch_not_found: The repository has no such branch

  • 409 app_config_unavailable: The envFrom app has no configuration to copy from

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project to create the app in

Pattern: ^[0-9a-fA-F]{24}$
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
namestring · min: 1 · max: 100Required

App name

Responses
201

Created

application/json
post/projects/{projectId}/apps
POST /v1/projects/{projectId}/apps HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1280

{
  "name": "text",
  "config": {
    "image": "text",
    "registryAuth": {
      "username": "text",
      "password": "text"
    },
    "ports": [
      {
        "port": 1,
        "protocol": "tcp"
      }
    ],
    "env": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ],
    "command": [
      "text"
    ],
    "entrypoint": [
      "text"
    ],
    "startupCommand": {
      "args": [
        "text"
      ],
      "user": "text",
      "timeoutSec": 1,
      "startPeriodSec": 1
    },
    "healthcheck": {
      "test": [
        "text"
      ],
      "intervalSec": 1
    },
    "restartPolicy": {
      "mode": "disabled",
      "startTimeoutSec": 1,
      "maxRetriesPerNode": 1,
      "maxErrorTolerance": 1,
      "numTasks": 1
    },
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": "amd",
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "us-west"
      ],
      "providers": [
        {
          "csp": "aws",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ]
  },
  "source": {
    "kind": "text",
    "installationId": 1,
    "repo": "text",
    "clone": {
      "sourceRepo": "text",
      "sourceRef": "text",
      "targetRepoName": "text",
      "targetVisibility": "private"
    },
    "branch": "text",
    "contextDir": "text",
    "dockerfilePath": "text",
    "autoDeploy": true,
    "dockerfileContent": "text"
  },
  "envFrom": {
    "projectId": "text",
    "appId": "text",
    "overrides": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ]
  }
}
{
  "id": "text",
  "projectId": "text",
  "name": "text",
  "guid": "text",
  "source": null,
  "image": null,
  "domain": null,
  "buildState": null,
  "access": {
    "role": "admin",
    "outside": true,
    "isCreator": true
  },
  "createdBy": {
    "userId": "text",
    "name": null,
    "email": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "status": {
    "state": "unknown",
    "targetState": "running",
    "nodes": [
      {
        "address": "text",
        "state": "text",
        "reportedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "endpoints": [
      {
        "port": 1,
        "protocol": "text",
        "address": null,
        "server": null
      }
    ],
    "errors": [
      {
        "type": "text",
        "message": "text",
        "at": "2026-01-01T00:00:00.000Z",
        "details": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ],
    "workOrders": [
      {
        "type": "text",
        "server": "text",
        "status": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "completedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "grid": {
      "fill": {
        "target": 1,
        "online": 1,
        "pending": 1,
        "converging": true
      },
      "idleReclaim": [
        {
          "gridId": "text",
          "warnedAt": "2026-01-01T00:00:00.000Z",
          "evictAt": "2026-01-01T00:00:00.000Z",
          "evictedAt": "2026-01-01T00:00:00.000Z",
          "cooldownEndsAt": "2026-01-01T00:00:00.000Z",
          "evidence": "text"
        }
      ],
      "queue": [
        {
          "gridId": "text",
          "position": 1,
          "queueLength": 1,
          "enqueuedAt": "2026-01-01T00:00:00.000Z",
          "held": true
        }
      ]
    },
    "pollAfterSec": 1
  },
  "config": {
    "image": "text",
    "imageTag": null,
    "registryUsername": null,
    "ports": [
      {
        "port": 1,
        "protocol": "text"
      }
    ],
    "env": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ],
    "command": [
      "text"
    ],
    "entrypoint": [
      "text"
    ],
    "startupCommand": {
      "args": [
        "text"
      ],
      "user": "text",
      "timeoutSec": 1,
      "startPeriodSec": 1
    },
    "healthcheck": {
      "test": [
        "text"
      ],
      "intervalSec": 1
    },
    "restartPolicy": {
      "mode": "text",
      "startTimeoutSec": 1,
      "maxRetriesPerNode": 1,
      "maxErrorTolerance": 1,
      "numTasks": 1
    },
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": null,
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "text"
      ],
      "providers": [
        {
          "csp": "text",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ],
    "domains": [
      "text"
    ]
  },
  "github": {
    "installationId": 1,
    "repo": "text",
    "url": "text",
    "branch": "text",
    "contextDir": "text",
    "dockerfilePath": null,
    "dockerfileOverride": true,
    "dockerfileContent": null,
    "autoDeploy": true,
    "clonedFrom": null
  },
  "defaultDomain": null,
  "start": {
    "state": "requested",
    "error": null
  },
  "buildId": null
}

Get an app with its full configuration and last known status

get

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}
GET /v1/projects/{projectId}/apps/{appId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "projectId": "text",
  "name": "text",
  "guid": "text",
  "source": null,
  "image": null,
  "domain": null,
  "buildState": null,
  "access": {
    "role": "admin",
    "outside": true,
    "isCreator": true
  },
  "createdBy": {
    "userId": "text",
    "name": null,
    "email": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "status": {
    "state": "unknown",
    "targetState": "running",
    "nodes": [
      {
        "address": "text",
        "state": "text",
        "reportedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "endpoints": [
      {
        "port": 1,
        "protocol": "text",
        "address": null,
        "server": null
      }
    ],
    "errors": [
      {
        "type": "text",
        "message": "text",
        "at": "2026-01-01T00:00:00.000Z",
        "details": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ],
    "workOrders": [
      {
        "type": "text",
        "server": "text",
        "status": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "completedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "grid": {
      "fill": {
        "target": 1,
        "online": 1,
        "pending": 1,
        "converging": true
      },
      "idleReclaim": [
        {
          "gridId": "text",
          "warnedAt": "2026-01-01T00:00:00.000Z",
          "evictAt": "2026-01-01T00:00:00.000Z",
          "evictedAt": "2026-01-01T00:00:00.000Z",
          "cooldownEndsAt": "2026-01-01T00:00:00.000Z",
          "evidence": "text"
        }
      ],
      "queue": [
        {
          "gridId": "text",
          "position": 1,
          "queueLength": 1,
          "enqueuedAt": "2026-01-01T00:00:00.000Z",
          "held": true
        }
      ]
    },
    "pollAfterSec": 1
  },
  "config": {
    "image": "text",
    "imageTag": null,
    "registryUsername": null,
    "ports": [
      {
        "port": 1,
        "protocol": "text"
      }
    ],
    "env": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ],
    "command": [
      "text"
    ],
    "entrypoint": [
      "text"
    ],
    "startupCommand": {
      "args": [
        "text"
      ],
      "user": "text",
      "timeoutSec": 1,
      "startPeriodSec": 1
    },
    "healthcheck": {
      "test": [
        "text"
      ],
      "intervalSec": 1
    },
    "restartPolicy": {
      "mode": "text",
      "startTimeoutSec": 1,
      "maxRetriesPerNode": 1,
      "maxErrorTolerance": 1,
      "numTasks": 1
    },
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": null,
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "text"
      ],
      "providers": [
        {
          "csp": "text",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ],
    "domains": [
      "text"
    ]
  },
  "github": {
    "installationId": 1,
    "repo": "text",
    "url": "text",
    "branch": "text",
    "contextDir": "text",
    "dockerfilePath": null,
    "dockerfileOverride": true,
    "dockerfileContent": null,
    "autoDeploy": true,
    "clonedFrom": null
  },
  "defaultDomain": null
}

Update the name, alerts, configuration or repository settings of an app. A running app is redeployed with the new configuration; while a GitHub-sourced app is still building, the change is applied by that build. Changing instances, hardware or volumes also needs compute:spend.

patch

Requires apps:write (Create, update, start, stop, restart and rebuild apps).

Also requires compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances) when instances, hardware or volumes change.

Also requires compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances) when source changes what is built (branch, contextDir, dockerfilePath, dockerfileContent).

Errors specific to this operation:

  • 409 app_source_unsupported: The app's image is uploaded from the dashboard, or source was given for an image app

  • 400 grid_to_serverless: A grid app cannot move back to serverless

  • 400 no_suitable_machines: No machine can run the new configuration; lower the hardware requirements

  • 429 grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas

  • 403 serverless_disabled: The change needs new serverless machines, or starts a build of a serverless app, and the organization keeps serverless capacity to its admins; target a grid

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
namestring · min: 1 · max: 100Optional

New app name

Responses
200

OK

application/json
patch/projects/{projectId}/apps/{appId}
PATCH /v1/projects/{projectId}/apps/{appId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1100

{
  "name": "text",
  "alerts": {
    "enabled": true,
    "emails": [
      "name@gmail.com"
    ],
    "delayMinutes": 1
  },
  "config": {
    "image": "text",
    "registryAuth": {
      "username": "text",
      "password": "text"
    },
    "ports": [
      {
        "port": 1,
        "protocol": "tcp"
      }
    ],
    "env": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ],
    "command": [
      "text"
    ],
    "entrypoint": [
      "text"
    ],
    "startupCommand": {
      "args": [
        "text"
      ],
      "user": "text",
      "timeoutSec": 1,
      "startPeriodSec": 1
    },
    "healthcheck": {
      "test": [
        "text"
      ],
      "intervalSec": 1
    },
    "restartPolicy": {
      "mode": "disabled",
      "startTimeoutSec": 1,
      "maxRetriesPerNode": 1,
      "maxErrorTolerance": 1,
      "numTasks": 1
    },
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": "amd",
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "us-west"
      ],
      "providers": [
        {
          "csp": "aws",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ]
  },
  "source": {
    "branch": "text",
    "contextDir": "text",
    "dockerfilePath": "text",
    "autoDeploy": true,
    "dockerfileContent": "text"
  }
}
{
  "id": "text",
  "projectId": "text",
  "name": "text",
  "guid": "text",
  "source": null,
  "image": null,
  "domain": null,
  "buildState": null,
  "access": {
    "role": "admin",
    "outside": true,
    "isCreator": true
  },
  "createdBy": {
    "userId": "text",
    "name": null,
    "email": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "status": {
    "state": "unknown",
    "targetState": "running",
    "nodes": [
      {
        "address": "text",
        "state": "text",
        "reportedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "endpoints": [
      {
        "port": 1,
        "protocol": "text",
        "address": null,
        "server": null
      }
    ],
    "errors": [
      {
        "type": "text",
        "message": "text",
        "at": "2026-01-01T00:00:00.000Z",
        "details": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ],
    "workOrders": [
      {
        "type": "text",
        "server": "text",
        "status": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "completedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "grid": {
      "fill": {
        "target": 1,
        "online": 1,
        "pending": 1,
        "converging": true
      },
      "idleReclaim": [
        {
          "gridId": "text",
          "warnedAt": "2026-01-01T00:00:00.000Z",
          "evictAt": "2026-01-01T00:00:00.000Z",
          "evictedAt": "2026-01-01T00:00:00.000Z",
          "cooldownEndsAt": "2026-01-01T00:00:00.000Z",
          "evidence": "text"
        }
      ],
      "queue": [
        {
          "gridId": "text",
          "position": 1,
          "queueLength": 1,
          "enqueuedAt": "2026-01-01T00:00:00.000Z",
          "held": true
        }
      ]
    },
    "pollAfterSec": 1
  },
  "config": {
    "image": "text",
    "imageTag": null,
    "registryUsername": null,
    "ports": [
      {
        "port": 1,
        "protocol": "text"
      }
    ],
    "env": [
      {
        "key": "text",
        "value": null,
        "secret": true
      }
    ],
    "command": [
      "text"
    ],
    "entrypoint": [
      "text"
    ],
    "startupCommand": {
      "args": [
        "text"
      ],
      "user": "text",
      "timeoutSec": 1,
      "startPeriodSec": 1
    },
    "healthcheck": {
      "test": [
        "text"
      ],
      "intervalSec": 1
    },
    "restartPolicy": {
      "mode": "text",
      "startTimeoutSec": 1,
      "maxRetriesPerNode": 1,
      "maxErrorTolerance": 1,
      "numTasks": 1
    },
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": null,
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "text"
      ],
      "providers": [
        {
          "csp": "text",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ],
    "domains": [
      "text"
    ]
  },
  "github": {
    "installationId": 1,
    "repo": "text",
    "url": "text",
    "branch": "text",
    "contextDir": "text",
    "dockerfilePath": null,
    "dockerfileOverride": true,
    "dockerfileContent": null,
    "autoDeploy": true,
    "clonedFrom": null
  },
  "defaultDomain": null,
  "buildId": null
}

Delete a stopped app (admins, or its creator). Fails with app_running while any node is still live. Irreversible.

delete

Requires apps:admin (Delete or move apps and manage who they are shared with).

Errors specific to this operation:

  • 409 app_running: A node is still running or stopping the app; stop it and retry once the status reports stopped

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
delete/projects/{projectId}/apps/{appId}
DELETE /v1/projects/{projectId}/apps/{appId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "deleted": true
}

Read the live status of an app from the runtime. Aggregate state, each server's container state, where each port answers, recent errors. Poll this after start, stop or delete.

get

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}/status
GET /v1/projects/{projectId}/apps/{appId}/status HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": "unknown",
  "targetState": "running",
  "nodes": [
    {
      "address": "text",
      "state": "text",
      "reportedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "endpoints": [
    {
      "port": 1,
      "protocol": "text",
      "address": null,
      "server": null
    }
  ],
  "errors": [
    {
      "type": "text",
      "message": "text",
      "at": "2026-01-01T00:00:00.000Z",
      "details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "workOrders": [
    {
      "type": "text",
      "server": "text",
      "status": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "grid": {
    "fill": {
      "target": 1,
      "online": 1,
      "pending": 1,
      "converging": true
    },
    "idleReclaim": [
      {
        "gridId": "text",
        "warnedAt": "2026-01-01T00:00:00.000Z",
        "evictAt": "2026-01-01T00:00:00.000Z",
        "evictedAt": "2026-01-01T00:00:00.000Z",
        "cooldownEndsAt": "2026-01-01T00:00:00.000Z",
        "evidence": "text"
      }
    ],
    "queue": [
      {
        "gridId": "text",
        "position": 1,
        "queueLength": 1,
        "enqueuedAt": "2026-01-01T00:00:00.000Z",
        "held": true
      }
    ]
  },
  "pollAfterSec": 1,
  "id": "text"
}

Check which servers could run an existing app: with its stored configuration, or with config layered on top to test a change before update_app. Nothing is changed.

post

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
Responses
200

OK

application/json
post/projects/{projectId}/apps/{appId}/placement
POST /v1/projects/{projectId}/apps/{appId}/placement HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 458

{
  "config": {
    "instances": {
      "min": 1,
      "max": 1
    },
    "stateful": true,
    "hardware": {
      "gpuCount": 1,
      "gpuModels": [
        "text"
      ],
      "gpuManufacturer": "amd",
      "gpuVramBytes": 1,
      "ramBytes": 1,
      "storageBytes": 1,
      "shmemBytes": 1
    },
    "placement": {
      "regions": [
        "us-west"
      ],
      "providers": [
        {
          "csp": "aws",
          "regions": [
            {
              "region": "text",
              "zones": [
                "text"
              ]
            }
          ]
        }
      ],
      "allowedIps": [
        "text"
      ]
    },
    "grids": {
      "ids": [
        "text"
      ],
      "priorities": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    },
    "volumes": [
      {
        "name": "text",
        "target": "text",
        "declaredSizeBytes": 1
      }
    ]
  }
}
{
  "placeable": true,
  "serversWithCapacity": 1,
  "serversWithoutCapacity": 1,
  "wakeable": 1,
  "wakeableAwaitingStock": 1,
  "provisionable": true,
  "rejections": [
    {
      "server": "text",
      "reason": "text"
    }
  ]
}

Ask the runtime to start an app. Returns once the request is accepted; poll the status to follow it.

post

Requires apps:write (Create, update, start, stop, restart and rebuild apps), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 402 balance_over_limit: The organization's balance is below the allowed negative limit; add credits and retry

  • 429 grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas

  • 403 serverless_disabled: The app would run on Kinesis serverless capacity, which the organization keeps to its admins; target a grid

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
202

Accepted

application/json
post/projects/{projectId}/apps/{appId}/start
POST /v1/projects/{projectId}/apps/{appId}/start HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "targetState": "running"
}

Ask the runtime to stop an app. Returns once the request is accepted; poll the status to follow it.

post

Requires apps:write (Create, update, start, stop, restart and rebuild apps).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
202

Accepted

application/json
post/projects/{projectId}/apps/{appId}/stop
POST /v1/projects/{projectId}/apps/{appId}/stop HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "targetState": "running"
}

Stop an app, wait for it to report stopped, then start it again. Waits up to waitSec (default 30); if the app is still stopping by then the start is issued anyway. Poll the status to follow the start.

post

Requires apps:write (Create, update, start, stop, restart and rebuild apps), compute:spend (Spend credits: start, scale or resize apps, provision or wake servers, rent spot instances).

Errors specific to this operation:

  • 402 balance_over_limit: The organization's balance is below the allowed negative limit; add credits and retry

  • 429 grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas

  • 403 serverless_disabled: The app would run on Kinesis serverless capacity, which the organization keeps to its admins; target a grid

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
waitSecinteger · max: 180Optional

Seconds to wait for the stop before starting, 0 to 180 (default 30)

Responses
202

Accepted

application/json
post/projects/{projectId}/apps/{appId}/restart
POST /v1/projects/{projectId}/apps/{appId}/restart HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 13

{
  "waitSec": 1
}
{
  "id": "text",
  "targetState": "text",
  "stoppedBeforeStart": true,
  "waitedSec": 1
}

Read a page of container logs for an app. Paging starts at the newest lines and moves back in time by default; inside a page, chunks and lines run oldest to newest, so the last line is the most recent.

get

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

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Query parameters
nodesstring[] · max: 50Optional

Server addresses to read from; omit for every server the app ran on

cursorNsstringOptional

Cursor from a previous page (nextCursorNs)

cursorintegerOptional

Unix time in milliseconds to seek to when no cursorNs is given; 0 or omitted means now

pageSizeinteger · min: 1 · max: 1000Optional

Lines per page, at most 1000 (default 200)

directionstring · enumOptional

Which way the next page moves from the cursor: older (the default) or newer. Lines inside a page are always chronological

Possible values:
Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}/logs
GET /v1/projects/{projectId}/apps/{appId}/logs HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "logs": [
    {
      "node": "text",
      "from": "2026-01-01T00:00:00.000Z",
      "to": "2026-01-01T00:00:00.000Z",
      "lines": [
        "text"
      ]
    }
  ],
  "nextCursorNs": null,
  "hasMore": true,
  "totalLines": 1
}

Resource usage of an app over a time range, bucketed per server

get

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

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Query parameters
startstring · date-timeOptional

Range start (ISO 8601); defaults to one hour before end

endstring · date-timeOptional

Range end (ISO 8601); defaults to now. At most 30 days after start

Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}/usage
GET /v1/projects/{projectId}/apps/{appId}/usage HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "start": "2026-01-01T00:00:00.000Z",
  "end": "2026-01-01T00:00:00.000Z",
  "intervalSeconds": 1,
  "series": [
    {
      "node": "text",
      "points": [
        {
          "at": "2026-01-01T00:00:00.000Z",
          "cpuNs": 1,
          "gpuNs": 1,
          "gpuMemBytesSecs": 1,
          "memBytesSecs": 1,
          "storageBytesSecs": 1,
          "logStorageBytesSecs": 1,
          "bwInBytes": 1,
          "bwOutBytes": 1
        }
      ]
    }
  ]
}

Move an app to another project of its organization. Admins may, and so may the app's creator. Nothing about the app itself changes.

post

Requires apps:admin (Delete or move apps and manage who they are shared with).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
targetProjectIdstringRequired

Project to move the app into

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
post/projects/{projectId}/apps/{appId}/move
POST /v1/projects/{projectId}/apps/{appId}/move HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "targetProjectId": "text"
}
{
  "id": "text",
  "projectId": "text",
  "name": "text",
  "guid": "text",
  "source": null,
  "image": null,
  "domain": null,
  "buildState": null,
  "access": {
    "role": "admin",
    "outside": true,
    "isCreator": true
  },
  "createdBy": {
    "userId": "text",
    "name": null,
    "email": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z"
}

How long the app's container logs are kept

get

Requires apps:read (View apps, their configuration and status).

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}/logs/retention
GET /v1/projects/{projectId}/apps/{appId}/logs/retention HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "days": 1,
  "isDefault": true
}

Set how many days the app's container logs are kept. 1 to 180; 0 goes back to the platform default

patch

Requires apps:write (Create, update, start, stop, restart and rebuild apps).

Errors specific to this operation:

  • 429 too_many_attempts: More than three log changes in a minute

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
daysinteger · max: 180Required

Days to keep; 0 for the default

Responses
200

OK

application/json
patch/projects/{projectId}/apps/{appId}/logs/retention
PATCH /v1/projects/{projectId}/apps/{appId}/logs/retention HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 10

{
  "days": 1
}
{
  "days": 1,
  "isDefault": true
}

Delete the app's container logs older than a point in time. Cannot be undone.

post

Requires apps:write (Create, update, start, stop, restart and rebuild apps).

Errors specific to this operation:

  • 429 too_many_attempts: More than three log changes in a minute

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Body
olderThanstring · date-timeRequired

Lines before this instant are deleted

Responses
200

OK

application/json
post/projects/{projectId}/apps/{appId}/logs/clear
POST /v1/projects/{projectId}/apps/{appId}/logs/clear HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "olderThan": "2026-01-01T00:00:00.000Z"
}
{
  "deletedCount": 1
}

The app's container logs as one text, oldest first. Every line is stamped with its time and server, up to maxBytes (1 MiB by default, 4 MiB at most). For a page at a time use apps.logs instead.

get

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

Errors specific to this operation:

  • 429 too_many_attempts: More than three log changes in a minute

Authorizations
AuthorizationstringRequired

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

Path parameters
projectIdstringRequired

Project id

Pattern: ^[0-9a-fA-F]{24}$
appIdstringRequired

App id

Pattern: ^[0-9a-fA-F]{24}$
Query parameters
nodesstring[] · max: 50Optional

Server addresses to include; omit for all

maxBytesinteger · min: 1024 · max: 4194304Optional

Stop after this many bytes of text; 1048576 by default

Responses
200

OK

application/json
get/projects/{projectId}/apps/{appId}/logs/export
GET /v1/projects/{projectId}/apps/{appId}/logs/export HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "text": "text",
  "lines": 1,
  "truncated": true
}
PreviousProjects
NextBuilds

Was this helpful?