API & OpenAPI

Use hlix's OpenAPI 3.1 contract directly or generate a client with open-source tooling.

The contract is the machine-readable description of every published hlix API operation. It describes authentication, workspace headers, request parameters, and documented responses in OpenAPI 3.1 format.

Prerequisites

An hlix API key and, for workspace-scoped operations, a workspace ID
For the generation example: Docker

Download the contract

The contract endpoint does not require authentication:

curl --fail --silent --show-error \
  https://docs.hlix.ai/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)"

The command exits successfully for OpenAPI 3.1.0 and prints the 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

Keep credentials out of URLs and committed commands. Read them from your shell or CI secret store; expanded header values remain available to the curl process.

Generate another language

Install an official SDK for TypeScript, Python, or Go. Generate a custom client when you need another language or different settings.

For example, this command pins OpenAPI Generator and creates an async Python client named hlix:

docker run --rm \
  --volume "$PWD:/local" \
  openapitools/openapi-generator-cli:v7.22.0 generate \
  --input-spec /local/hlix-openapi.json \
  --generator-name python \
  --additional-properties packageName=hlix,library=httpx \
  --output /local/generated/hlix-python

python -m pip install ./generated/hlix-python

The generated client reflects the downloaded contract. Keep the contract and generator version with your integration so you can reproduce it. See OpenAPI Generator’s language options for other targets. Report a contract mismatch to support@hlix.ai.

The Python and Go guides include working client examples. The TypeScript SDK adds retry, typed-error, upload and streaming helpers.

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: check the resource ID and your access to the selected Workspace.
409: expected revision/state is stale or another operation currently owns the transition.
A generated field is typed unknown: validate the returned value before using its fields.
Regeneration changes code you did not expect: compare the contract’s info.version with the one you generated from last time.