Harthelm Docs
REST APIEvents

Live events (SSE)

A `text/event-stream` of `Event`s the caller may see (filtered by the authorizer), fed by PostgreSQL `LISTEN/NOTIFY`. Each event is `id: <n>`, `event: <type>`, `data: <Event as JSON>`; a comment line (`: ping`) is sent every 25 s. There is no replay: the first event is always `ready`, sent once the subscription is live, and a client refetches what it shows after every `ready` (also after a reconnect).

Generated from openapi/harthelm.yaml at v1.5.0
GET
/events

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.

Query Parameters

team?integer

Only events of this team (the ready event is always sent).

Formatint64
Range1 <= value

Response Body

The event stream; it stays open until the client or the server closes it.

text/event-stream
  1. response
type*EventType
  • ready: the subscription is live; refetch what the page shows. Always the first event.
  • workspace.created, workspace.updated (state, status text or settings changed), workspace.deleted (soft delete), workspace.restored: carry the full workspace.
  • workspace.purged: the workspace is gone for good; only workspace_id and team_id.
  • operation.updated: an operation changed state or progress text; carries the full operation.
  • landscape.updated: the landscape of workspace_id changed (Sync, Teardown, run switch, a service's status); refetch GET /workspaces/{ws}/landscape.
  • stage.updated: a run of stage changed (started, a step moved, finished); carries stage and run_id; refetch GET /workspaces/{ws}/stages/{stage}.
  • managed_service.updated: the managed service managed_service_id of team_id changed (settings, status, details, a delete or the purge of its tombstone; workspace_id for one bound to a landscape); refetch GET /managed-services/{ms} (404 once purged).
  • org.updated: the organization org_id was renamed.
  • org.deleted: the deletion of org_id started (it shows as deleting), and again when it is gone; refetch GET /orgs (404 once gone).
  • team.created, team.updated (renamed, settings, quota), team.deleted (the deletion started, and again when the team is gone): team_id; refetch GET /teams/{team} (404 once gone).
  • members.updated: the members of org_id, team_id or workspace_id changed (added, role, removed, workspace owner); refetch the member list.
  • invites.updated: an invitation of org_id (and team_id) was created, accepted, revoked or renewed, or its mail state moved.
  • owner_transfers.updated: an ownership transfer of workspace_id (team_id) was offered, accepted, declined or cancelled; refetch GET /me/owner-transfers and GET /workspaces/{ws}/owner-transfers. Sent to those with workspace.view on it, which includes the user it is offered to.
  • access.changed: the caller's own roles changed; refetch GET /orgs, GET /teams and the resources on the page (permissions may have grown or shrunk). Sent only to that user.
  • domain.updated: the custom domain domain_id of team_id was added, changed (settings, routes, a verification or certificate status) or removed; refetch GET /teams/{team}/domains (the domain is gone when it is no longer listed). Shown with team.view.
Value in"ready""workspace.created""workspace.updated""workspace.deleted""workspace.restored""workspace.purged""operation.updated""landscape.updated""stage.updated""managed_service.updated""org.updated""org.deleted""team.created""team.updated""team.deleted""members.updated""invites.updated""owner_transfers.updated""access.changed""domain.updated"
at*string
Formatdate-time
team_id?ID

Numeric resource id.

Formatint64
Range1 <= value
workspace_id?ID

Numeric resource id.

Formatint64
Range1 <= value
workspace?
operation?

A long-running action. It ends in succeeded or failed and stays readable for 7 days.

stage?StageName
Value in"prepare""test""run"
run_id?ID

Numeric resource id.

Formatint64
Range1 <= value
managed_service_id?string
Formatuuid
org_id?string
Formatuuid
domain_id?string
Formatuuid
curl -X GET 'https://console.example.com/api/v1/events'
{  "type": "ready",  "at": "2019-08-24T14:15:22Z",  "team_id": 1,  "workspace_id": 1,  "workspace": {    "id": 1,    "team_id": 1,    "name": "string",    "plan": "string",    "base_image": "string",    "git": {      "provider": "string",      "repo": "string",      "ref": "string"    },    "storage_gib": 1,    "availability": "always",    "restricted": true,    "state": "creating",    "status_detail": "string",    "urls": {      "ide": "string",      "dev": "string"    },    "dev_service": {      "name": "string",      "state": "running",      "wake_seconds": 0,      "needs": [        "string"      ],      "failing_needs": [        "string"      ]    },    "vault_id": 1,    "single_node": true,    "idle_timeout_minutes": 1,    "last_archived_at": "2019-08-24T14:15:22Z",    "restored_from": 1,    "upgrade_pending": true,    "created_by": 1,    "owner_id": 1,    "needs_owner": true,    "permissions": [      "string"    ],    "created_at": "2019-08-24T14:15:22Z",    "deleted_at": "2019-08-24T14:15:22Z",    "purge_after": "2019-08-24T14:15:22Z"  },  "operation": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "kind": "string",    "state": "pending",    "target": "string",    "detail": "string",    "error": {      "type": "about:blank",      "title": "string",      "status": 100,      "detail": "string",      "instance": "string",      "errors": [        {          "pointer": "string",          "line": 1,          "column": 1,          "message": "string",          "code": "string",          "subject": "string"        }      ],      "held_by_deleted": {        "workspaces": 0,        "storage_gib": 0      },      "failed_team": {        "id": 1,        "name": "string",        "reason": "string"      }    },    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "finished_at": "2019-08-24T14:15:22Z"  },  "stage": "prepare",  "run_id": 1,  "managed_service_id": "77427583-c503-4b42-8d68-8e0a3b2c8384",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c"}

Replace the workspace env vars

Replaces the whole set (the UI's bulk `.env` upload sends everything). New terminals see the change at once, prepare and test at their next start, services at the next Sync, which pins every service's environment. Needs `landscape.manage`.

Add a default repository

Team admins only. Adding an existing entry again changes its access.