# API & OpenAPI

**The contract is the machine-readable description of every published hlix API operation.** It is OpenAPI 3.1, generated from the same Zod validators the server enforces at runtime plus explicit response schemas — so a shape it describes is a shape the API actually validates.

## Prerequisites

- Nothing to download the contract; the endpoint is unauthenticated
- An hlix API key and a workspace ID to call any operation
- For code generation: OpenAPI Generator `7.22.0`, or the generator of your choice

## Download the contract

The contract endpoint does not require authentication:

```bash
curl --fail --silent --show-error \
  https://server.hlix.ai/v1/api/openapi.json \
  --output hlix-openapi.json
```

Verify it before code generation:

```bash
node -e "const d=require('./hlix-openapi.json'); if(d.openapi!=='3.1.0') process.exit(1); console.log(d.info.version)"
```

Expected result: OpenAPI `3.1.0` and the current contract version.

## Call the API

Authenticated operations use two headers:

- `x-api-key`: authenticates the user
- `X-Organization-Id`: selects the workspace

```bash
curl --fail --silent --show-error \
  --header "x-api-key: $HLIX_API_KEY" \
  --header "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  https://server.hlix.ai/v1/api/projects
```

Do not put credentials in the URL or command itself. Environment expansion still makes the value available to the process, so use your shell and CI secret controls appropriately.

## How the contract is produced

The contract follows one reviewable chain:

1. Hono routes validate requests with exported Zod schemas.
2. The public-operation registry selects which routes form the supported API.
3. The document builder converts route syntax, attaches request/response schemas, security, and API metadata.
4. `apps/backend/openapi.json` is emitted and checked in so contract changes have a visible diff.
5. `openapi-typescript` generates the private transport schema used by `@hlix/api-client`.
6. `@hlix/sdk` reads its public method types directly from those generated paths.

Steps 1–4 happen inside hlix; steps 5–6 are what you can reproduce, against the contract you downloaded above. Never hand-edit a generated client to "fix" a mismatch — regenerate it, and if the contract itself is wrong, report it.

## Generate another language

The OpenAPI document is the portable integration point. You do not need a commercial code-generation service to start.

Common open-source choices include:

- [OpenAPI Generator](https://openapi-generator.tech/) for broad language coverage
- [Kiota](https://learn.microsoft.com/openapi/kiota/) for strongly typed clients across several Microsoft-supported languages
- language-focused generators when you need a smaller, idiomatic surface

Every command operates on the contract file you downloaded — nothing here needs access to hlix's source:

```bash
npx @openapitools/openapi-generator-cli generate \
  -i hlix-openapi.json \
  -g python \
  -o ./hlix-client
```

Expected result: a client package whose operations match the [API reference](/api/reference/) one for one. Pin the generator version so a regeneration is reproducible; hlix's own previews use OpenAPI Generator `7.22.0`.

Example with OpenAPI Generator:

```bash
docker run --rm \
  --volume "$PWD:/local" \
  openapitools/openapi-generator-cli generate \
  --input-spec /local/hlix-openapi.json \
  --generator-name python \
  --output /local/generated/hlix-python
```
**Generated does not mean published:** A generated client can call the API, but it is not a stable first-party package until its authentication defaults, workspace scoping, retries, errors, uploads, streams, packaging, tests, and release lifecycle are verified. The TypeScript SDK is the current opinionated implementation. [Python](/sdk/python/) and [Go](/sdk/go/) source previews are generated with a pinned OpenAPI Generator, but are not yet registry/module releases.

## Compatibility

The API contract version is independent of the CLI, SDK, and platform release numbers:

- major: a previous client can break, paired with a new URL prefix;
- minor: additive route or field changes;
- patch: documentation-only contract corrections.

The current URL prefix remains `/v1/api`. A package version bump does not automatically bump the API version.

## If a request or a generation fails

- `401`: the API key is missing or invalid.
- `403`: the authenticated user cannot perform that action in the selected workspace.
- `404`: the resource is absent **or not visible**; do not infer cross-tenant existence.
- `409`: expected revision/state is stale or another operation currently owns the transition.
- A generated field becomes `unknown`: the published response schema may not pin that body yet; do not invent a stronger local type.
- Local generated diff after no intended contract change: regenerate from a clean checkout and investigate registry/schema drift.

## Next steps

[TypeScript SDK](/sdk/typescript/)
  [Python SDK preview](/sdk/python/)
  [Tasks](/running/tasks/)
  [Versions & releases](/releases/versioning/)