Harthelm Docs
REST APILandscape

Read harthelm.yml

The profile's file (`harthelm.yml`, or `harthelm.<profile>.yml`) from `/data/app`, read through the IDE agent, with its SHA-256 (also the `ETag`), the HEAD commit and the profiles that exist. 404 when the profile's file does not exist (the editor starts from a template); 409 "The workspace is not running." without an IDE pod (an asleep IDE is woken first, as for a Plan); 413 above 1 MiB; 422 when the file is not UTF-8. Needs `workspace.view`.

Generated from openapi/harthelm.yaml at v1.5.0
GET
/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])?)?$

Response Body

The file.

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 GET 'https://console.example.com/api/v1/workspaces/1/landscape/config'
{  "path": "string",  "content": "string",  "sha256": "string",  "commit": "string",  "profiles": [    "string"  ]}

Add or duplicate a profile

Creates `harthelm.<name>.yml` (*Add profile* with `content`, *Duplicate* with `from`, exactly one of the two; 422 otherwise). The write is the agent's create (`If-None-Match: *`), so an existing file is 409 `name-taken`. It does not select the profile. Needs `workspace.code`; audited as `landscape.config_write`.

Get the landscape

The synced landscape: state, profile, `spec_hash`, the run switch and one entry per service with its observed status. An empty landscape has no services. Needs `workspace.view`. The `ETag` is the quoted `spec_hash` (`"empty"` before the first Sync).