Harthelm Docs
REST APILandscape

Write harthelm.yml

Writes the profile's file through the IDE agent, the one file write the console has. `If-Match` is the quoted SHA-256 the editor read; `If-None-Match: *` creates a file that must not exist yet; neither is 428. A file whose hash is not `If-Match` (or that exists under `If-None-Match: *`) is 412 with problem `config-changed`: the editor re-reads and offers *Save and override*, which sends the new hash. The agent writes atomically (a temporary file in `/data/app` renamed over the old one, mode kept) and does not validate: a file with a syntax error is saved as written, and the next Plan answers 422 `invalid-config`. The content is UTF-8 without NUL bytes (422 with pointer `/content`), at most 1 MiB (413). Nothing else changes: the synced landscape keeps running until a Sync. Needs `workspace.code`; audited as `landscape.config_write` (profile and the new hash).

Generated from openapi/harthelm.yaml at v1.5.0
PUT
/workspaces/{ws}/landscape/config

Authorization

cookie__Host-harthelm_session<token>

Browser session of the UI (12 h idle, 7 days absolute). State-changing requests also need the header Harthelm-CSRF: 1 and a matching Origin.

Path Parameters

ws*integer

Numeric resource id.

Formatint64
Range1 <= value

Query Parameters

profile?string

A profile; absent or empty for harthelm.yml.

Match^([a-z0-9]([-a-z0-9]{0,30}[a-z0-9])?)?$

Header Parameters

If-Match?string

ETag of the version the change is based on. Declared optional so that the server, not the request binder, answers a missing header with 428.

If-None-Match?"*"

*: create the resource; it must not exist yet (412 when it does).

Value in"*"

Request Body

application/json
  1. body
content*string

The new file, UTF-8 without NUL bytes, at most 1 MiB.

Lengthlength <= 1048576

Response Body

The file as written.

application/json
  1. response

A profile's harthelm.yml as the IDE agent read or wrote it.

path*string

Relative to /data/app: harthelm.yml or harthelm.<profile>.yml.

content*string

The file as UTF-8.

sha256*string

Lower-case hex SHA-256 of the bytes on disk; the editor's version (send it quoted as If-Match).

commit?string

HEAD of /data/app; absent outside a repository or before the first commit.

profiles*array<string>

The profiles whose files exist, "" for harthelm.yml, sorted.

curl -X PUT 'https://console.example.com/api/v1/workspaces/1/landscape/config' \  -H 'Content-Type: application/json' \  -d '{  "content": "string"}'
{  "path": "string",  "content": "string",  "sha256": "string",  "commit": "string",  "profiles": [    "string"  ]}

Tear the landscape down

One transaction stops every service, sets their desired replicas to 0 and the landscape state to `torn-down`; the reconcile removes the services' Deployments, Services and Secrets and their routes. The code in `/data/app` and the vault stay; a Sync rebuilds everything. Needs `landscape.manage`.

Stage and service logs

Step output of the workspace. Without `follow`, the history as NDJSON (`application/x-ndjson`, one `LogEntry` per line, oldest first, at most `limit` lines) from the log backend. With `follow=true`, a `text/event-stream`: the agents' ring buffers since `since`, then live lines, each `event: log` with a `LogEntry` as data; `event: end` when the followed run finished; a `: ping` comment every 25 s. Filters combine; `replica` is a pod name. Needs `workspace.view`.