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:

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

Verify it before code generation:

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

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 for broad language coverage
• 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:

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 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:

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 and 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 SDKSupported auth, retry, error, upload, and streaming behaviour, without rebuilding it.

Python SDK previewA generated client for the same contract, installed from source.

TasksWhat the task endpoints do, including the stream's four properties.

Versions & releasesHow the API contract's version moves independently of every package.