# API reference

**This is the endpoint-level reference for the hlix API: 90 operations across 8 resources.** Every page under it is generated from `openapi.json` at build time, so it cannot describe an operation the contract does not publish.

Contract version `1.0.0`, OpenAPI 3.1. To download the document itself or generate a client from it, see [API & OpenAPI](/api/openapi/).

## Prerequisites

- An hlix API key — create one in Developer tools → API keys
- The ID of a workspace you can act in

```bash
export HLIX_API_KEY='…'
export HLIX_WORKSPACE_ID='<workspace-id>'
export HLIX_BASE_URL='https://server.hlix.ai'
```

## Resources

| Resource | Operations | What it covers |
| --- | --- | --- |
| [Projects](/api/reference/projects/) | 28 | Projects, their repositories, roadmap, artifacts and Coding Workspace. |
| [Tasks](/api/reference/tasks/) | 9 | Standalone tasks and their review evidence. |
| [Cycles](/api/reference/cycles/) | 22 | Multi-task units of work and their conversations. |
| [Imports](/api/reference/imports/) | 7 | Secure project snapshot upload, verification and finalization. |
| [Reports](/api/reference/reports/) | 5 | Agency portfolio health and client-safe reporting views. |
| [Client invoices](/api/reference/client-invoices/) | 9 |  |
| [Client billing profile](/api/reference/client-billing-profile/) | 4 |  |
| [Revisions](/api/reference/revisions/) | 6 |  |

## Authentication

Every operation takes the same two headers:

```bash
curl -sS "$HLIX_BASE_URL/v1/api/projects" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"
```

`x-api-key` authenticates a **user**; it names no workspace. `X-Organization-Id` selects the tenant that user acts in. A browser client sends its session cookie instead of the key, and may omit the header when the session already has an active organization — but server-side automation should always pass it explicitly, so a prior session cannot decide the tenant for you.
**Absent and forbidden look identical:** A resource in another workspace answers `404`, not `403`. That is deliberate: a `403` would confirm the resource exists. Never infer cross-tenant existence from a status code.
**For AI agents:** Do not scrape these pages to learn the API. Fetch the contract itself — `GET /v1/api/openapi.json`, unauthenticated — and read it as JSON. It is the same document these pages are generated from, it is always current, and it carries the full schemas that a table can only summarise.

Use these pages for what the contract cannot express: which operations exist for a job, what a `404` deliberately hides, and which surfaces are outside the contract entirely.

## What is not here

The contract publishes the operations above and nothing else. Several surfaces the product exposes are **not** in it, and therefore have no generated client method:

- **Memories** (`/v1/api/memories`) — use the dashboard or a direct HTTP call. See [Context, memory & DNA](/concepts/context-memory/).
- **Model and harness configuration** (`/v1/api/model-config`, `/v1/api/providers`) — see [Connect your agents](/guides/connect-agents/).
- **Logs** (`/v1/api/logs`) — there is no log stream, only plain reads. See [Tasks](/running/tasks/#watching-a-task).
- **Audit log**, **pending requests**, **environments**, **packs**, **secrets**, and the live agent stream/steer endpoints.

An operation missing from this reference is missing from the contract, which means the SDKs cannot reach it either. That is a deliberate boundary, not an oversight: the published contract is the part hlix commits to keeping compatible.

## If a request fails

- `400` — the body failed schema validation, or the request named no active organization.
- `401` — no valid session or API key. Check `x-api-key`.
- `403` — authenticated, but not a member of the named workspace.
- `404` — no such resource in this workspace, or a resource that was never shared with you.
- `409` — a compare-and-swap lost, or another operation owns the transition. Re-read the head and retry.
- `429` — too many requests.
- `5xx` — the operation failed server-side. Retry only where an idempotency key makes it safe.

## Next steps

[Projects](/api/reference/projects/)
  [Tasks](/api/reference/tasks/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)