Environments & endpoints

hlix is one hosted environment, reached through three hostnames: the API, the dashboard, and these docs. Every application endpoint lives under a versioned prefix; a small, deliberate set sits outside it. This page is the map.

Prerequisites

• An API key and your Workspace ID from Developer tools → API keys, for anything authenticated
• The CLI installed, for the resolution examples

The hostnames

Host	What it serves
server.hlix.ai	The API, the published OpenAPI contract, and the inbound integration webhooks
app.hlix.ai	The dashboard
docs.hlix.ai	These docs, including the machine-readable formats

The API prefix

Every application endpoint is under /v1/api:

https://server.hlix.ai/v1/api/projects
https://server.hlix.ai/v1/api/tasks
https://server.hlix.ai/v1/api/cycles
https://server.hlix.ai/v1/api/audit-log

v1 is the contract version, not a build number. The full, generated list is in the API reference, and the contract itself is served at https://server.hlix.ai/v1/api/openapi.json — unauthenticated, so a generator can fetch it without credentials.

What sits outside the prefix

Three things, each for a reason:

Path	Why it is unversioned
/health	A liveness probe should not depend on the contract version
/webhooks/*	The URL is registered with an external service — GitHub, Linear, Slack, Telegram — and must stay stable across contract versions
/	A plain landing page

The OAuth install and callback endpoints for those same integrations are versioned, under /v1/api/integrations/*. Only the raw inbound receivers are not.

Authenticating a request

Two headers, and both matter:

curl -sS "https://server.hlix.ai/v1/api/projects" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

x-api-key says who; X-Organization-Id says which Workspace. A browser client sends the session cookie instead of the key, and the sign-in endpoints under /v1/api/auth/* accept only that cookie flow — an API key cannot be used to sign in, only to act.

The health check

curl -sS https://server.hlix.ai/health

Expected result:

{"status": "ok", "service": "hlix-backend", "timestamp": "2026-08-28T09:14:22.481Z"}

This is a liveness probe, not a status page

/health takes no credentials and touches no data. It answers “is the service accepting requests”, and it answers ok even when a dependency behind it is degraded. It is not a health summary of your Workspace. hlix publishes no status page and no uptime commitment.

How the CLI chooses a host

HLIX_BASE_URL is optional and defaults to https://server.hlix.ai. When more than one source names a host, the CLI resolves them in a fixed order — first match wins:

1. An explicit flag on the command
2. An HLIX_* environment variable
3. The nearest .hlix/config.json, walking up from the working directory
4. The stored credential from hlix auth login
5. The built-in default

hlix status prints which source won, so you never have to guess:

hlix status

api         https://server.hlix.ai (from credential)

The environment variables are HLIX_API_KEY, HLIX_BASE_URL, HLIX_WORKSPACE_ID, and HLIX_CONFIG_HOME for the config directory.

How the SDKs choose a host

The clients do not share one default:

Client	Default host
CLI	https://server.hlix.ai
Python and Go preview clients	https://server.hlix.ai
TypeScript SDK	None — baseUrl is required

const hlix = new Hlix({
  baseUrl: 'https://server.hlix.ai',
  apiKey: process.env.HLIX_API_KEY,
})

If a request does not reach where you expect

• 404 on a path you copied from these docs. Check the /v1/api prefix. server.hlix.ai/projects is not a route; server.hlix.ai/v1/api/projects is. The three exceptions are /health, /webhooks/* and /.
• {"error": "No active organization"} with 400. The request carried no X-Organization-Id and the credential has no Workspace to fall back on. Send the header.
• {"error": "Not a member of this organization"} with 403. The Workspace ID is valid but belongs to an account you are not a member of. Copy it from the API keys page rather than from another environment’s notes.
• The CLI is talking to the wrong host. Run hlix status and read the parenthetical — it names the winning source. A stale .hlix/config.json in a parent directory beats your stored credential.
• A TypeScript SDK call fails before it leaves the process. baseUrl has no default in that client. Pass it explicitly.
• A webhook you registered never arrives. The receiver URL is unversioned — server.hlix.ai/webhooks/…, with no /v1/api. Re-check the URL you gave the external service against its integration page.
• /health returns ok while your work is failing. Expected: it is a liveness probe with no data access. Look at the task’s own run and logs instead.

Where to go next

If you want to…	Read
See every endpoint and its shapes	API reference
Set up credentials for the first time	Authenticate
Understand what runs behind these hosts	Platform architecture
Register an integration webhook	Integrations

Next steps

AuthenticateCreating a key, signing in, and pointing the CLI at a Workspace.

API & OpenAPIThe published contract these hosts serve, and how to generate a client from it.

Platform architectureHow hlix decides, runs and delivers work behind these hostnames.

Reliability & maintenanceWhat runs on a schedule, and what to expect when something is idle.