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

Apps and templates

Discover, create and update container applications and ready-made templates.

Discover, create and update container applications and ready-made templates.

These are action names. In default compact mode, call the indicated group tool with {"action":"<action-name>","params":{...}}; the arguments below go inside params. In ?mode=all, call the action name directly with those arguments. browse_github and read_docs are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and structuredContent; failures use isError and structuredContent.error.

list_apps

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

Group: apps · Behavior: Read

Compact tool: apps · Action: list_apps

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation
REST
Required scopes

apps.list

GET /apps

apps:read

Arguments

Argument
Type
Required
Description

projectId

string

No

Limit the list to one project

limit

integer

No

Items per page, 1 to 200 (default 50)

cursor

string

No

nextCursor from the previous page; omit for the first page

org

string

No

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

Complete input schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Limit the list to one project"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "org": {
      "description": "Slug of an organization (see orgs.list) to list only what is in it or shared into it",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}

Result

  • apps (array<object>): See the complete response schema below.

  • nextCursor (string or null): Pass as cursor to fetch the next page; null on the last page

Response schema: apps.list

list_templates

The gallery's app templates as ready-made create_app configurations. Ollama chat with a chosen model, vLLM servers, ...: pass a template's config to create_app with a name, edited as needed; notes says what a template needs filled in first.

Group: apps · Behavior: Read

Compact tool: apps · Action: list_templates

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation
REST
Required scopes

templates.list

GET /templates

Authenticated connection; organization and resource permissions still apply

Arguments

Argument
Type
Required
Description

search

string

No

Case-insensitive substring of the name or image

category

"llm_general" / "llm_performance" / "general"

No

Only templates of this category

Complete input schema

Result

  • templates (array<object>): See the complete response schema below.

  • galleryUrl (string): The dashboard gallery, where the same templates are deployed by hand

Response schema: templates.list

get_app

Get an app with its full configuration and last known status

Group: apps · Behavior: Read

Compact tool: apps · Action: get_app

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation
REST
Required scopes

apps.get

GET /projects/{projectId}/apps/{appId}

apps:read

Arguments

Argument
Type
Required
Description

projectId

string

Yes

Project id

appId

string

Yes

App id

Complete input schema

Result

  • id (string): App id

  • projectId (string): See the complete response schema below.

  • name (string): See the complete response schema below.

  • guid (string): Runtime identifier of the app

  • source (string or null): Where the image comes from: Docker Hub, a registry link, GitHub or an upload

  • image (string or null): See the complete response schema below.

  • domain (string or null): Hostname the app answers on: the default custom domain, else the Kinesis-issued one

  • buildState (string or null): Build pipeline state for GitHub-sourced apps

  • access (object): See the complete response schema below.

  • createdBy (object or null): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read

  • createdAt (string): ISO 8601 timestamp (UTC)

  • status (object): Status as last cached; use the status endpoint for a live read

  • config (object or null): See the complete response schema below.

  • github (object or null): Repository settings of a GitHub-sourced app

  • defaultDomain (string or null): Custom domain shown as the app's address in the dashboard; null for the Kinesis-issued one

Response schema: apps.get

check_placement

See whether any server could run an app or a configuration change. Reports servers with capacity now, hibernated ones that would fit once woken, whether one can be provisioned on demand, and why sampled servers were rejected, before creating, updating or starting. With appId the app's stored configuration is checked, config (placement-relevant fields only) layered on top; without appId, config describes an app to be created in the project.

Group: apps · Behavior: Read

Compact tool: apps · Action: check_placement

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation
REST
Required scopes

apps.placement

POST /projects/{projectId}/apps/{appId}/placement

apps:read

projects.placement

POST /projects/{projectId}/placement

apps:read

Arguments

Argument
Type
Required
Description

projectId

string

Yes

Project id

appId

string

No

App id

config

object

No

The placement-relevant parts of an app configuration: instances, stateful, hardware, placement, grids, volumes

Complete input schema

Result

apps.placement

  • placeable (boolean): A server can take the app now, a hibernated one would fit once woken, or one can be provisioned

  • serversWithCapacity (integer): Servers that match and have room now

  • serversWithoutCapacity (integer): Servers that match but are full

  • wakeable (integer): Hibernated servers that would match once woken (power_servers wake, or the automatic wake-up on start)

  • wakeableAwaitingStock (integer): Of wakeable, servers whose provider has no stock right now, so a wake would not land yet

  • provisionable (boolean): The platform can provision a matching cloud machine on demand for a serverless app

  • rejections (array<object>): Why sampled servers cannot take the app; each distinct reason appears first, then repeats

Response schema: apps.placement

**`projects.placement`**

  • placeable (boolean): A server can take the app now, a hibernated one would fit once woken, or one can be provisioned

  • serversWithCapacity (integer): Servers that match and have room now

  • serversWithoutCapacity (integer): Servers that match but are full

  • wakeable (integer): Hibernated servers that would match once woken (power_servers wake, or the automatic wake-up on start)

  • wakeableAwaitingStock (integer): Of wakeable, servers whose provider has no stock right now, so a wake would not land yet

  • provisionable (boolean): The platform can provision a matching cloud machine on demand for a serverless app

  • rejections (array<object>): Why sampled servers cannot take the app; each distinct reason appears first, then repeats

Response schema: projects.placement

create_app

Create an app from an image or a GitHub repository and start it. config.image pulls an image; source builds a connected repository (one without a Dockerfile takes an inline source.dockerfileContent); the start begins spending credits. envFrom copies another app's environment variables, secret values included, on the server. Omitted config fields take the dashboard defaults (1 GiB RAM, 1 GB disk, 1 to 3 instances, no GPU). Returns the app and how the automatic start went; call get_app_status to follow it, or get_build with buildId for a repository app. read_docs(deploy) lists every field.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: create_app

MCP annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: true

Permissions and REST equivalents

Operation
REST
Required scopes

apps.create

POST /projects/{projectId}/apps

apps:write, compute:spend

Arguments

Argument
Type
Required
Description

name

string

Yes

App name

config

object

Yes

Initial configuration; image is required unless source is set

source

object

No

Build the image from a GitHub repository the caller connected (members of the project's organization); omit to pull config.image

envFrom

object

No

Copy another app's environment variables, secret values included, on the server (developer access to that app); use overrides instead of config.env

projectId

string

Yes

Project to create the app in

idempotencyKey

string

No

Unique string without whitespace; send the same one with the same arguments when retrying after a timeout, and the original result comes back instead of acting twice

Complete input schema

Result

  • id (string): App id

  • projectId (string): See the complete response schema below.

  • name (string): See the complete response schema below.

  • guid (string): Runtime identifier of the app

  • source (string or null): Where the image comes from: Docker Hub, a registry link, GitHub or an upload

  • image (string or null): See the complete response schema below.

  • domain (string or null): Hostname the app answers on: the default custom domain, else the Kinesis-issued one

  • buildState (string or null): Build pipeline state for GitHub-sourced apps

  • access (object): See the complete response schema below.

  • createdBy (object or null): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read

  • createdAt (string): ISO 8601 timestamp (UTC)

  • status (object): Status as last cached; use the status endpoint for a live read

  • config (object or null): See the complete response schema below.

  • github (object or null): Repository settings of a GitHub-sourced app

  • defaultDomain (string or null): Custom domain shown as the app's address in the dashboard; null for the Kinesis-issued one

  • start (object): How the automatic start after creation went

  • buildId (string or null): First build of a GitHub-sourced app; null for image apps

Response schema: apps.create

Operation-specific errors: 402 balance_over_limit, 429 app_creation_quota_exceeded, 400 no_suitable_machines, 429 grid_quota_exceeded, 403 serverless_disabled, 503 github_not_configured, 404 github_installation_not_found, 404 github_repo_not_found, 502 upstream_github, 404 github_branch_not_found, 409 app_config_unavailable.

update_app

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.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: update_app

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: true

Permissions and REST equivalents

Operation
REST
Required scopes

apps.update

PATCH /projects/{projectId}/apps/{appId}

apps:write

Conditional

instances, hardware or volumes change

compute:spend

Conditional

source changes what is built (branch, contextDir, dockerfilePath, dockerfileContent)

compute:spend

Arguments

Argument
Type
Required
Description

name

string

No

New app name

alerts

object

No

Health-check email alerts

config

object

No

Configuration changes; list fields replace the stored list, object fields merge per key

source

object

No

Repository settings of a GitHub-sourced app (members of the project's organization); a change to the branch, directories or Dockerfile starts a rebuild

projectId

string

Yes

Project id

appId

string

Yes

App id

Complete input schema

Result

  • id (string): App id

  • projectId (string): See the complete response schema below.

  • name (string): See the complete response schema below.

  • guid (string): Runtime identifier of the app

  • source (string or null): Where the image comes from: Docker Hub, a registry link, GitHub or an upload

  • image (string or null): See the complete response schema below.

  • domain (string or null): Hostname the app answers on: the default custom domain, else the Kinesis-issued one

  • buildState (string or null): Build pipeline state for GitHub-sourced apps

  • access (object): See the complete response schema below.

  • createdBy (object or null): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read

  • createdAt (string): ISO 8601 timestamp (UTC)

  • status (object): Status as last cached; use the status endpoint for a live read

  • config (object or null): See the complete response schema below.

  • github (object or null): Repository settings of a GitHub-sourced app

  • defaultDomain (string or null): Custom domain shown as the app's address in the dashboard; null for the Kinesis-issued one

  • buildId (string or null): Build started by a source change; null when nothing was rebuilt

Response schema: apps.update

Operation-specific errors: 409 app_source_unsupported, 400 grid_to_serverless, 400 no_suitable_machines, 429 grid_quota_exceeded, 403 serverless_disabled.

move_app

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

Group: apps · Behavior: Write

Compact tool: apps_write · Action: move_app

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation
REST
Required scopes

apps.move

POST /projects/{projectId}/apps/{appId}/move

apps:admin

Arguments

Argument
Type
Required
Description

targetProjectId

string

Yes

Project to move the app into

projectId

string

Yes

Project id

appId

string

Yes

App id

Complete input schema

Result

  • id (string): App id

  • projectId (string): See the complete response schema below.

  • name (string): See the complete response schema below.

  • guid (string): Runtime identifier of the app

  • source (string or null): Where the image comes from: Docker Hub, a registry link, GitHub or an upload

  • image (string or null): See the complete response schema below.

  • domain (string or null): Hostname the app answers on: the default custom domain, else the Kinesis-issued one

  • buildState (string or null): Build pipeline state for GitHub-sourced apps

  • access (object): See the complete response schema below.

  • createdBy (object or null): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read

  • createdAt (string): ISO 8601 timestamp (UTC)

Response schema: apps.move
PreviousProjects
NextApp lifecycle

Was this helpful?