Apps

An app is a Docker container deployed and managed on an instance. Apps can be created from a custom image (documented here) or deployed from a reusable template (see App templates). Creating, updating, and deleting an app are asynchronous: they return a workflow you poll until the app settles. Start, stop, and restart are also asynchronous and return a workflow.

All path parameters are required strings containing numeric IDs.

List apps in a workspace

GET/v1/workspaces/{wid}/appsList apps in a workspace

Lists all apps owned by a workspace, with pagination.

Path parameters

Name	Type	Description
wid	string	Workspace ID

Query parameters

Name	Type	Description
q	string	Quick search by name, image, or ID
name	string	Filter by app name (partial match)
image	string	Filter by Docker image (partial match)
state	string	Filter by resource state (PENDING, AVAILABLE, FAILED, SUSPENDED, DELETING, UNPLACED)
instance	string	Filter to a specific instance ID

All query parameters are optional, including the shared pagination parameters.

Returns 200 OK with a KeysetResultEnrichedAppViewContainerLiveStats object. Its items contain app summaries with live stats flattened into each app object when available. Pagination fields are total, page, limit, has_next, has_previous, after, and before.

curl -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  "https://api.galaxygate.net/v1/workspaces/1524141521580666880/apps"

List apps on an instance

GET/v1/instances/{iid}/appsList apps on an instance

Lists all apps deployed on the given instance. Accepts the same query and pagination parameters as the workspace-level list.

Path parameters

Name	Type	Description
iid	string	Instance ID

Query parameters

Same optional parameters as List apps in a workspace, including instance. The path always restricts results to the specified instance.

Returns 200 OK with the same paged response and flattened live stats as the workspace list.

Create an app

POST/v1/instances/{iid}/appsCreate an app

Creates a new Docker container app on the given instance and starts a deploy workflow. Requires the Editor role or higher on the workspace.

To deploy from a pre-built template instead, use Deploy from template.

Path parameters

Name	Type	Description
iid	string	Instance ID

Request body

Field	Type	Required	Description
name	string	yes	App name, unique within the workspace
image	string	yes	Docker image including tag, for example nginx:latest
environment	object or null	no	String-valued environment variables passed to the container
mounts	AppVolumeMount[] or null	no	Volume mounts (see below)
ports	PortMapping[] or null	no	Port mappings (see below)
domain	string or null	no	Custom domain name for the app, for example grafana.galaxygate.app. Requires at least one port marked http: true

AppVolumeMount fields

All fields are required.

Field	Type	Description
host_path	string	Absolute path on the instance host, for example /data/myapp
container_path	string	Absolute mount path inside the container, for example /var/lib/data
read_only	boolean	Mount the path read-only

PortMapping fields

All fields are required.

Field	Type	Description
host_port	integer	Port exposed on the instance host, from 1 to 65535. Port 2375 is reserved.
container_port	integer	Port the container process listens on, from 1 to 65535
protocol	string	TCP or UDP
http	boolean	Whether this port serves HTTP traffic eligible for a custom domain. At most one port may be true, and it must use TCP.

curl -X POST -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:latest",
    "environment": { "NGINX_PORT": "80" },
    "ports": [
      { "host_port": 8080, "container_port": 80, "protocol": "TCP", "http": true }
    ],
    "mounts": [
      { "host_path": "/data/nginx", "container_path": "/usr/share/nginx/html", "read_only": false }
    ],
    "domain": "my-nginx.galaxygate.app"
  }' \
  "https://api.galaxygate.net/v1/instances/101/apps"

Returns 201 Created with a WorkflowWithResource object containing workflow and resource. Poll GET /v1/apps/{aid} until its state is AVAILABLE.

Fetch an app

GET/v1/apps/{aid}Fetch app detail

Returns the full configuration of an app, including port mappings and a live container stats snapshot.

Path parameters

Name	Type	Description
aid	string	App ID

Returns 200 OK with an EnrichedAppDetailViewAppDetailLive object. Configuration, ports, and live stats share the top level. Live stats fields are omitted when unavailable.

Configuration fields include id, name, image, state, owner, instance, environment, mounts, ports, container_id, domain, locked, and template. Live stats fields are running, cpu, memory_usage, memory_limit, network_rx, network_tx, app_id, instance_id, and updated_at. IDs are strings. updated_at is Unix milliseconds.

Update an app

PUT/v1/apps/{aid}Update an app

Updates an app's configuration and redeploys the container. All fields are optional. Omitted or null fields are left unchanged. Triggers an asynchronous redeploy.

Path parameters

Name	Type	Description
aid	string	App ID

Request body

Field	Type	Description
image	string or null	New Docker image including tag
environment	object or null	Replacement set of string-valued environment variables
mounts	AppVolumeMount[] or null	Replacement volume mounts (see Create an app for field details)
ports	PortMapping[] or null	Replacement port mappings (see Create an app for field details)

Returns 200 OK with a WorkflowWithResource object containing workflow and resource. Poll GET /v1/apps/{aid} until state is AVAILABLE.

Delete an app

DELETE/v1/apps/{aid}Delete an app

Stops and removes the container, then deletes the app and its port allocations. This is destructive and asynchronous.

Path parameters

Name	Type	Description
aid	string	App ID

Returns 200 OK with a WorkflowWithResource object containing workflow and resource.

Start an app

POST/v1/apps/{aid}/startStart an app

Starts a stopped app container. Asynchronous.

Path parameters

Name	Type	Description
aid	string	App ID

Returns 200 OK with a WorkflowWithResource object containing workflow and resource.

Stop an app

POST/v1/apps/{aid}/stopStop an app

Stops a running app container. Asynchronous.

Path parameters

Name	Type	Description
aid	string	App ID

Returns 200 OK with a WorkflowWithResource object containing workflow and resource.

Restart an app

POST/v1/apps/{aid}/restartRestart an app

Stops and starts an app container. Asynchronous.

Path parameters

Name	Type	Description
aid	string	App ID

Returns 200 OK with a WorkflowWithResource object containing workflow and resource.

Fetch app metrics

GET/v1/apps/{aid}/metricsFetch app metrics

Returns historical CPU, memory, and network time-series metrics for an app container, sourced from Prometheus. Values are raw. The panel normalizes them for display.

Path parameters

Name	Type	Description
aid	string	App ID

Query parameters

Name	Type	Required	Description
start	integer	yes	Window start, Unix seconds
end	integer	yes	Window end, Unix seconds
step	integer	yes	Resolution in seconds (minimum 15)

Returns 200 OK with an AppMetrics object with four PromMatrix series:

Field	Unit	Notes
cpu	cores	Fractional core usage. 1.0 = one core fully utilized. Divide by the container's allocated core count for a 0-1 ratio.
memory	bytes	Current container memory usage. Compare against the memory limit from the top-level live stats fields for a utilization ratio.
network_rx	bytes/sec	Inbound network throughput. Returns 0 for the first ~60 seconds after a container starts and across restarts.
network_tx	bytes/sec	Outbound network throughput. Same semantics as network_rx.

Fetch app logs

GET/v1/apps/{aid}/logsFetch app logs

Returns recent container logs. Include follow to keep the connection open and receive new lines as server-sent events.

Path parameters

Name	Type	Description
aid	string	App ID

Query parameters

Name	Type	Required	Description
tail	integer	no	Number of recent lines, from 1 to 10000. Defaults to 100.
follow	boolean	no	Include this parameter to stream logs. Omit it to fetch logs once. Its presence selects streaming, even with false.

Returns 200 OK with text/plain for a single fetch, or text/event-stream when follow is present.

curl -N -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Accept: text/event-stream" \
  "https://api.galaxygate.net/v1/apps/1483754921000984881/logs?tail=100&follow=true"