Container App

API for single-machine container apps

Version: 0.1.0

Server

  • URL: https://api.kopernik.us/v0
    • Kopernik.us API server

Paths

/resource/containerapp/{providerUid}

GET

List container apps

List container apps for the specified provider

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
nextToken query string ❌ Token for the next page of container apps, if there are more items to fetch
maxResults query integer ❌ Maximum number of container apps to fetch
jq query string ❌ JQ filter expression to filter the results. Only resources where the expression evaluates to a truthy value are included. The expression is applied to each resource’s JSON representation. Uses jq 1.7 syntax.

Responses:

POST

Create container app

Initiate creation of a new single-machine container app for the specified provider, and return an Action representing the create operation.

A container app is implemented as a machine plus an agent-managed Docker container. The API provisions the machine, prepares storage and networking, pulls the image, and starts the container with the provided runtime settings.

Before calling this endpoint, choose a machine image that supports container apps by checking the image property supportsContainerApp.

The operation starts the action immediately, and then waits a configurable amount of time for the action to complete. If the action completes within the wait time, then the operation returns 200 OK with the Action object in completed state. If the action does not complete within the wait time, then the operation returns 202 Accepted with the Action object in initiated state. Action status and result can be checked later using the Action API.

Note that this operation’s result represents Action, not the created resource, i.e. returns successful HTTP response (200 or 202) even if the underlying Create resource operation fails. If the action cannot be initiated, then an error response is returned.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ❌ Unique identifier of the region to create the resource in. Must be provided either as this query parameter or in the request body; when both are given, they must be equal.
waitTime query number ❌ Maximum time to wait for the action to complete with 200 OK before returning 202 Accepted; in seconds

Request Body:

Content Type: application/json

Schema: ContainerAppCreate

Responses:

  • 200: Container app created

  • 202: Container app create initiated

  • 400: Argument validation error

/resource/containerapp/{providerUid}/{resourceUid}

GET

Get container app

Get container app details

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the container app

Responses:

DELETE

Delete container app

Initiate deletion of a container app, and return an Action representing the delete operation. Note that this operation returns successful HTTP response (200 or 202) even if the Delete action fails. Error response is returned if the Action cannot be initiated. Resource deletion status and result are available in the returned Action object, or via the Action API later.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the container app to delete
attachedVolumesDeletePolicy query AttachedVolumesDeletePolicy ❌ Controls what happens to block storage volumes attached to the underlying machine. Use error to reject deletion when attached data volumes still exist, or a delete policy value to remove them together with the container app.
waitTime query number ❌ Maximum time to wait for the action to complete with 200 OK before returning 202 Accepted; in seconds

Responses:

  • 200: Container app deletion completed

  • 202: Container app deletion initiated

  • 400: Argument validation error

  • 404: Container app not found

/resource/containerapp/{providerUid}/{resourceUid}/app/logs/{streamName}

GET

Get container app logs

Get retained log readings for the managed container. Log payloads are returned as gzip-compressed, base64-encoded chunks.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the container app
streamName path ContainerAppLogStreamName ✅ Name of the container app log stream, either “stdout” or “stderr”
from query string ❌ Cursor for incremental reads. Pass the last seen reading UID from the previous response to continue reading newer entries. When omitted, the stream is read from the oldest retained entries.
maxResults query integer ❌ Maximum number of log readings to fetch; actual number of readings may be less, but never exceed the limit.

Responses:

Schemas

ContainerImage

Container image

Type: object

Properties:

Name Type Required Description
id string ✅ Image ID, e.g. “nginx:latest”.
digest string Optional image digest (e.g. sha256:…) to pin the image for reproducibility.

ContainerImageRepositoryCredentials

Image repository credentials

Type: object

Properties:

Name Type Required Description
username string ✅ Username for the image repository
password string ✅ Password for the image repository

ContainerAppEnvVar

Environment variable for the container

Type: object

Properties:

Name Type Required Description
name string ✅ Environment variable name
value string ✅ Environment variable value

ContainerAppRuntimeProps

Runtime properties for the container

Type: object

Properties:

Name Type Required Description
env array<ContainerAppEnvVar> Environment variables for the container
ports array<BindPort> Exposed container ports. These entries are passed to the docker container run command as “-p <host_port>:<container_port>” arguments.
restartPolicy string enum Docker restart policy for the managed container. Defaults to always. Template-based apps may inherit template-defined defaults for some runtime properties.
bindMounts array<BindMount> When specified, lists volume bind targets for the Docker container instance. These entries are passed to the docker container run command as “-v :” arguments. For example, for MySQL you may attach an additional block storage volume to the machine, mount it on the host as /mnt/data, and bind it into the container as /var/lib/mysql so that database files survive replacement of the machine root disk.

ContainerApp

Container app is a virtual machine instance with a user-provided Docker container. It takes care of provisioning the machine, attaching and mounting volumes, downloading the image, launching the container, collecting status, and exposing logs.

Composition: allOf

Type: object

Properties:

Name Type Required Description
machine Machine ✅ Underlying machine instance
container ContainerAppContainer ✅ Container running the container app
templateUid string Unique identifier of the template if the container app was created from a template
containerImage ContainerImage Container image used by the container app

BindPort

A host-to-container port binding.

Type: object

Properties:

Name Type Required Description
hostPort integer ✅ Host port number.
containerPort integer Container port number. Defaults to hostPort.
protocol string enum Network protocol. Default is “tcp”.

BindMount

A host-to-container file system mount.

Type: object

Properties:

Name Type Required Description
hostPath string Path in the host machine filesystem to bind to the container. When it is the mount point of a volume attached to the machine, the container is started once that volume is mounted: a container binding a host path is given that path as it stands when the container is created, so starting it any earlier would leave the application writing to the root disk while the volume stays empty.
containerPath string Path in the container filesystem which is bound to the host filesystem.

ContainerAppCreate

Request to create a new container app.

There are two supported usage patterns:

  1. Provide containerImage and runtimeProps directly to create an app from a custom image.
  2. Provide templateUid together with the template’s containerImage to create from a template.

When templateUid is used, the server validates that the submitted image matches the template image. Required template environment variables must be supplied either explicitly in runtimeProps.env or through defaults defined by the template.

Type: object

Properties:

Name Type Required Description
machineConfiguration MachineCreate ✅ Configuration for the underlying machine. When creating from a template, you can optionally attach additional block storage volumes and then bind them into the container via runtimeProps.bindMounts. Template bind mount recommendations are advisory and are not enforced by the API.
templateUid string Optional. When set, create the container app from an app template. The template supplies the image identity, environment variable definitions, recommended bind mount targets, and default port mappings.
containerImage ContainerImage ✅ Container image to use for the container app. This field is always required. When templateUid is set, it must match the template image.
containerImageRepositoryCredentials ContainerImageRepositoryCredentials Optional credentials for pulling the container image from a private registry
runtimeProps ContainerAppRuntimeProps Runtime properties for the container. When templateUid is set, runtimeProps.ports may be omitted to inherit template ports.

ContainerAppResourceResponse

Response with container app

Composition: allOf

Type: object

Properties:

Name Type Required Description
resource ContainerApp ✅

ContainerAppPagedResourceResponse

Response with paged container apps

Composition: allOf

Type: object

Properties:

Name Type Required Description
resources array<ContainerApp> ✅

ContainerAppContainer

Container running the container app

Type: object

Properties:

Name Type Required Description
state string enum ✅ State of the Docker container running the container app
status string ✅ Human-readable status of the Docker container running the container app

ContainerAppLogStreamName

Name of the container app log stream, either “stdout” or “stderr”

Type: enum

Values:

  • stdout
  • stderr

ContainerAppLogStreamReading

Reading of a container app log stream

Type: object

Properties:

Name Type Required Description
uid string ✅ Unique identifier of the log reading; use this value as the next from cursor
data string ✅ Log payload for the stream, gzip-compressed and base64-encoded

ContainerAppLogStreamReadingResponse

Response with container app log stream readings

Composition: allOf

Type: object

Properties:

Name Type Required Description
container ContainerAppContainer ✅ Current state of the Docker container running the container app
streamName ContainerAppLogStreamName ✅
readings array<ContainerAppLogStreamReading> ✅
Last updated October 30, 2026Send feedback