Guides
Quickstart
Get started with the hzel API.
Base URL
All API requests target the backend at:
https://api.hzel.org/api/v1Authentication
hzel uses bearer tokens. Obtain one via OAuth or by creating a Personal Access Token (PAT) in the dashboard under Settings → Developer.
Include the token in every request:
Authorization: Bearer <your-token>See the Authentication guide for the full flow.
Create a container
The container is automatically started after provisioning — state progresses from "provisioning" to "running" once the node confirms the boot. See the ContainerRecord structure for the full field reference.
POST
https://api.hzel.org/api/v1/containers| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer <token>. Accepted auth methods: PAT, OAuth app token, JWT. |
Content-Type | Required | Must be application/json. |
x-csrf-token | Session auth only | Session-bound CSRF token. Required only when authenticating via session cookie. Automatically skipped for Authorization: Bearer requests. |
List your containers
GET
https://api.hzel.org/api/v1/containers| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer <token>. Accepted auth methods: PAT, OAuth app token, JWT. |
Start a container
Replace {id} with the container UUID.
POST
https://api.hzel.org/api/v1/containers/{id}/start| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer <token>. Accepted auth methods: PAT, OAuth app token, JWT. |
x-csrf-token | Session auth only | Session-bound CSRF token. Required only when authenticating via session cookie. |
Stop a container
POST
https://api.hzel.org/api/v1/containers/{id}/stop| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer <token>. Accepted auth methods: PAT, OAuth app token, JWT. |
x-csrf-token | Session auth only | Session-bound CSRF token. Required only when authenticating via session cookie. |
Restart a container
POST
https://api.hzel.org/api/v1/containers/{id}/restart| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer <token>. Accepted auth methods: PAT, OAuth app token, JWT. |
x-csrf-token | Session auth only | Session-bound CSRF token. Required only when authenticating via session cookie. |
What's next
- Read about WebSocket endpoints for terminal and command streaming.
- Understand the Security Model.
- Browse Error Codes to handle API errors correctly.