Your first Hostbrid API request: keys, permissions and cURL

The REST API lets a script or application connect to services in your Hostbrid account. Before automating changes, make a read request, check that you can see the expected resources and understand the permission each operation needs. The public reference is generated from the panel’s active routes; use it as the source of truth when endpoints change.

1. Create and store a key

Open Settings → API keys and create a key. Its full value is shown once. Store it in a secrets manager or your environment’s secure mechanism; do not commit it to Git, put it in browser JavaScript, or paste it into a prompt or screenshot. If someone sees it, revoke it and create another.

A newly created key can read. Permissions to write, operate machines or delete are separate; some must be requested from support. Grant only the permission your task needs. A key stays active until you revoke it; it does not expire after a short time.

2. Make a read request

Define HOSTBRID_API_KEY in your terminal’s protected environment and list your sites with a GET request:

curl --fail-with-body \
  -H "Authorization: Bearer $HOSTBRID_API_KEY" \
  https://my.hostbrid.com/api/sites/v1/sites/

The key starts with nxp_. If your tool cannot set Authorization, you can send the same key in X-API-Key. Do not use your panel session token or a JWT: the customer API authenticates with the long-lived key.

This example only reads. Before creating or changing a resource, check the method, expected body and permission in the OpenAPI reference. The console displays the schema but does not run requests from your browser. Each key has its own API rate limit; avoid polling in a loop when nothing has changed.

3. Read the result before continuing

Treat the response as data from your own account. Check the HTTP status and JSON before marking a task complete. A 200 does not by itself prove that the change you wanted was saved; a read response only confirms that read.

Response	What to check
`401`	The key is missing, copied incorrectly, revoked, or the header format is wrong.
`403`	The key lacks the required permission. Check the scope shown in the reference; do not guess methods.
`404`	The route or resource is not available in your account. Resources belonging to another account are not disclosed.
`429`	The per-key rate limit was exceeded. Reduce request frequency and avoid unnecessary repeats.

Do not blindly retry a POST that may create an order or resource: first check whether the earlier operation succeeded. Keep authorization headers out of logs and screenshots.

After your first request

For the full catalogue, per-operation permissions and request schemas, open the REST API reference. If you prefer terminal tasks, read the CLI guide. To connect a compatible AI assistant over MCP, see API, CLI and MCP for Hostbrid automation and the guide to connecting an AI assistant.

If you are automating a hardware purchase and lifecycle, follow the dedicated server API guide.

This guide does not grant permissions, purchase a service or prove that an arbitrary script is safe. Start with reads and add write permissions only for a specific action you need.