# 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](https://app.hlix.ai/developer-tools/api-keys), for anything authenticated
- The [CLI installed](/getting-started/install/), 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`**:

```text
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](/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:

```bash
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

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

Expected result:

```json
{"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:

```bash
hlix status
```

```text
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](/sdk/python/) and [Go](/sdk/go/) preview clients | `https://server.hlix.ai` |
| [TypeScript SDK](/sdk/typescript/) | **None — `baseUrl` is required** |

```ts
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](/integrations/).
- **`/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](/api/reference/) |
| Set up credentials for the first time | [Authenticate](/getting-started/authentication/) |
| Understand what runs behind these hosts | [Platform architecture](/platform/architecture/) |
| Register an integration webhook | [Integrations](/integrations/) |

## Next steps

[Authenticate](/getting-started/authentication/)
  [API & OpenAPI](/api/openapi/)
  [Platform architecture](/platform/architecture/)
  [Reliability & maintenance](/platform/reliability/)