API and automation

Everything in Harthelm goes through one REST API. The console uses it with your browser session, and hart and your scripts use it with an API key. Whatever you can click, you can automate.

The APICopy Anchor Link

The API lives under /api/v1 of your console's address:

https://console.example.com/api/v1

Every installation serves its own description at /api/v1/openapi.yaml and a browsable reference at /api/docs. The REST API reference on this site lists every operation of this release.

API keysCopy Anchor Link

An API key acts as you: it can do everything you can do. Keys look like hart_<id>_<secret>.

• Create one under Account settings → API keys → Add API key. Give it a name and an expiry, or Never. The key is shown once; Harthelm keeps only a fingerprint.
• hart login creates one for the command line, named "hart on <hostname>".
• Regenerate a key to replace its secret; the old one stops working at once.
• Delete a key to revoke it at once, also on workspace addresses.

Send it as Authorization: Bearer <key> (or Harthelm-Authorization: Bearer <key>) to the API, and as Harthelm-Authorization: Bearer <key> to a private workspace address. Keep keys as secret as your password.

Long-running actionsCopy Anchor Link

Creating a workspace, Sync and other actions outlive their request. They answer 202 with an operation, which you poll at /api/v1/operations/<id> until it ends in succeeded or failed. hart … --wait does that for you.

Live eventsCopy Anchor Link

/api/v1/events is a stream of server-sent events about what you may see: a workspace changed, an operation moved on, a landscape was synced. The console uses it to stay current without reloading. There is no replay: after each ready event, read the state you show again.

hart and the consoleCopy Anchor Link

hart is a thin client of the same API: every command maps to one or a few operations, with the same permissions and the same error messages. Its exit codes tell a script what went wrong without parsing text; see Exit codes.

Which tool for which jobCopy Anchor Link

Next stepsCopy Anchor Link