Projects and roles¶

A project holds servers, SSH keys, firewall groups, snapshots, ISOs, actions and orders, and the people who manage them. Each person has one role in each project they belong to. Paths address a project by its slug, which is the project's id in every path and never changes: /projects/acme/servers/.

You create, rename and delete projects, and invite and remove their members, in the console. The API lists the projects you belong to and reads one.

Endpoints¶

Endpoint	What it does
GET `/projects/`	List projects
GET `/projects/{slug}/`	Get a project

Roles¶

	Member	Admin	Owner
Read everything, and poll actions and orders
Power, reboot and reinstall servers, and take and restore snapshots
Manage hostnames, SSH keys, firewalls, ISOs and reverse DNS
Order servers, upgrade them, buy bandwidth and cancel servers
Rename the project, and manage its members and invitations, in the console
Delete the project, in the console

A request your role doesn't allow answers 403 insufficient_role. A project you are not a member of answers 404 not_found, the same as one that doesn't exist, so a 404 never tells anyone a project exists.

A read-only key can only read, whatever your role.

Transferring a server to another account is done in the console. The API has no endpoint for it.

Project readiness¶

A new project takes a moment to set up. Until it is ready, its ready field is false and every endpoint for its servers and other resources answers 403 project_not_ready. If the project's owner has no billing account yet, those endpoints answer 403 billing_account_required instead.

The project object¶

{
  "id": 7,
  "name": "Acme",
  "slug": "acme",
  "ready": true,
  "role": "owner",
  "created_at": "2026-10-19T10:00:00Z"
}

Field	Type	Description
`id`	integer	The project's id. Paths use the slug instead.
`name`	string	A label you can change in the console. It never appears in paths.
`slug`	string	The project's id in paths. It never changes.
`ready`	boolean	`false` while the project is being set up.
`role`	string	Your role in it: `owner`, `admin` or `member`.
`created_at`	string	When it was created.

Projects¶

List projects¶

GET /projects/

Any member · Read-only keys: yes · Returns 200 Project[]

The projects you are a member of, by name, with your role in each. A user without a project gets an empty list.

curl https://console.hosthatch.com/api/v1/projects/ \
  -H "Authorization: Bearer $HOSTHATCH_API_KEY"

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {"id": 7, "name": "Acme", "slug": "acme", "ready": true, "role": "owner", "created_at": "2026-10-19T10:00:00Z"}
  ]
}

Get a project¶

GET /projects/{slug}/

Any member · Read-only keys: yes · Returns 200 Project

One project you are a member of. Any other slug answers 404 not_found.

curl https://console.hosthatch.com/api/v1/projects/acme/ \
  -H "Authorization: Bearer $HOSTHATCH_API_KEY"

Errors¶

Status	Code	When
403	`insufficient_role`	Your role doesn't allow it.
403	`billing_account_required`	The project's owner has no billing account yet.
403	`project_not_ready`	The project is still being set up.
404	`not_found`	No such project, or you are not a member.