Xeonr Developer Docs
API SpecificationApps

Create App Version

POST
/containers.api.v1.AppService/CreateAppVersion

Adds an immutable (environment, port, workspace) version under an App and, when promote is set, makes it the active version in the same call. port must be 1-65535; the environment must belong to the App's namespace (PermissionDenied otherwise); working_dir must be absolute and clean (InvalidArgument). Returns the version and the App.

Access: namespace OPERATOR or above (write)

Authorization

BearerAuth
AuthorizationBearer <token>

A namespace-scoped API key (cpk_…) for machines, or a Xeonr Auth OIDC token for humans. The key's namespace and role are pinned server-side.

In: header

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/json

appId?string
Length1 <= length <= 64
environmentId?string

Must belong to the App's namespace.

Length1 <= length <= 64
port?integer
Range1 <= value <= 65535
workspace?Deprecated

Deprecated: use workspaces. Treated as a single-element list when set.

label?string
Lengthlength <= 4096
promote?boolean

promote makes this the active version as soon as it is created, which is what an ordinary deploy wants. False creates it dormant, for staging a version before cutting traffic to it. validate:skip a bool has no bounds

workspaces?

Filesystems every replica of this version sees. Supersedes workspace; setting both is an error rather than a merge.

Itemsitems <= 1000
workingDir?string

Where the workload starts. Absolute; empty selects the default, which differs by primitive on purpose:

sandbox the first read-write mount — an interactive user has to land somewhere writable job the first read-write mount — inputs are already staged there app the IMAGE'S OWN WORKDIR. An App runs an image built elsewhere and that WORKDIR is part of its contract, so the platform does not override it just because the version happens to declare a writable mount.

Set it explicitly when the default is wrong: a monorepo mounted at /workspace whose build runs in /workspace/apps/web has no other way to say so, and relying on the default couples the working directory to the ORDER of the mount list, which is not something a caller expects to matter.

Lengthlength <= 4096
[key: string]?never

Response Body

application/json

application/json

curl -X POST "https://containers.xeonr.io/containers.api.v1.AppService/CreateAppVersion" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "version": {
    "versionId": "string",
    "appId": "string",
    "environmentId": "string",
    "port": 0,
    "workspace": {
      "snapshotId": "string",
      "mountPath": "string",
      "readOnly": true,
      "workspaceId": "string",
      "ephemeral": true,
      "ephemeralFromSnapshotId": "string",
      "volume": {
        "sizeMb": "string",
        "seedSnapshotId": "string",
        "cacheKey": "string"
      }
    },
    "state": "APP_VERSION_STATE_UNSPECIFIED",
    "label": "string",
    "createdAtUnix": "string",
    "workspaces": [
      {
        "snapshotId": "string",
        "mountPath": "string",
        "readOnly": true,
        "workspaceId": "string",
        "ephemeral": true,
        "ephemeralFromSnapshotId": "string",
        "volume": {
          "sizeMb": "string",
          "seedSnapshotId": "string",
          "cacheKey": "string"
        }
      }
    ],
    "workingDir": "string"
  },
  "app": {
    "appId": "string",
    "namespace": "string",
    "label": "string",
    "scaling": {
      "minInstances": 0,
      "maxInstances": 0,
      "concurrency": 0,
      "idleTimeoutSec": 0,
      "activationTimeoutSec": 0
    },
    "resources": {
      "cpuMillis": 0,
      "memoryMb": 0,
      "ephemeralMb": 0,
      "pids": 0
    },
    "env": {
      "property1": "string",
      "property2": "string"
    },
    "egress": {
      "egressPolicyId": "string"
    },
    "state": "APP_STATE_UNSPECIFIED",
    "createdAtUnix": "string",
    "updatedAtUnix": "string",
    "hostname": "string",
    "activeVersionId": "string",
    "autoStart": true,
    "access": "APP_ACCESS_UNSPECIFIED",
    "key": "string"
  }
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}

Create App POST

Creates an empty App in a namespace: an assigned hostname, a freshly minted key and an operational envelope, serving nothing until a version is created and promoted. access UNSPECIFIED is stored as KEY. Scaling defaults: max_instances 1 (raised to min_instances if lower), concurrency 100, idle_timeout_sec 300, activation_timeout_sec 30. NotFound for an unknown namespace; FailedPrecondition when the egress policy needs the proxy and App egress is not configured; Unimplemented without cluster access. **Access:** namespace OPERATOR or above (write)

Delete App POST

Deletes an App: tears down every replica pod, revokes the replicas' workspace-mount keys, deletes their ephemeral workspaces, then removes the App and its record. **Access:** namespace OPERATOR or above (write)