Harthelm Docs
REST APIWorkspaces

Mint an IDE entry URL

Returns the URL the shell sets as the code-server iframe `src`: the IDE host's `/__harthelm/enter?t=<token>` with a single-use token (60 s, audience = IDE host). Needs `workspace.code`. The router turns the token into the workspace cookie.

Generated from openapi/harthelm.yaml at v1.5.0
POST
/workspaces/{ws}/ide-entry

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

Response Body

The entry URL.

application/json
  1. response
url*string

The IDE host's /__harthelm/enter?t=<token> as an absolute HTTPS URL, valid once.

expires_at*string
Formatdate-time
curl -X POST 'https://console.example.com/api/v1/workspaces/1/ide-entry'
{  "url": "string",  "expires_at": "2019-08-24T14:15:22Z"}

Agent channel (WebSocket)

A WebSocket upgrade (subprotocol `harthelm.agent.v1`) that core relays to the workspace agent: shared terminals, status, git head and the read-only file API. Core checks `workspace.view` and passes the agent a signed claim with the caller's permissions; the agent refuses terminal input without `workspace.exec`. Frames are `ChannelMessage` JSON text frames and binary terminal frames.

Mint a preview URL for the Preview tab

The URL the Preview tab sets as its iframe `src`: a dev host of the workspace (`port`, default the entry host 3000) at `path` (default `/`). For a private host (the workspace is restricted) it is the host's `/__harthelm/enter?t=<token>` with a single-use token (60 s, audience = that host) that carries `path`: the router sets the workspace cookie, posts `harthelm:cookie-ok` or `harthelm:cookie-blocked` to the console and continues to `path`. For a public host it is the plain URL. The Preview tab falls back to a new tab when the cookie is blocked or the app refuses to be framed. A port without a dev host is 409 (nothing is served there). Needs `workspace.view`.