Harthelm Docs
REST APIWorkspaces

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`.

Generated from openapi/harthelm.yaml at v1.5.0
POST
/workspaces/{ws}/preview-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

Request Body

application/json
  1. body
port?integer

The dev host's port; 3000 is the entry host with every route, other ports are public ports.

Range1 <= value <= 65535
Default3000
path?string

Path and query on the host to open.

Match^/
Lengthlength <= 2048
Default"/"

Response Body

The preview URL.

application/json
  1. response
url*string

Absolute HTTPS URL for the iframe src: /__harthelm/enter?t=<token> on a private host (valid once), else the host's URL at path.

private*boolean

The host needs the workspace cookie; listen for the cookie messages.

expires_at?string

When the entry token expires; absent for a public host.

Formatdate-time
curl -X POST 'https://console.example.com/api/v1/workspaces/1/preview-entry' \  -H 'Content-Type: application/json' \  -d '{}'
{  "url": "string",  "private": true,  "expires_at": "2019-08-24T14:15:22Z"}

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.

Create a workspace

Returns at once; the workspace moves creating → cloning → running as the Operation proceeds. A Git source needs a connection to its provider (problem `git-connection-required`) and read access to the repository. The origin repository is added to the workspace's git access list with write access.