OpenAPI specification

Download the spec, generate type-safe clients, and stay in sync with API changes

Akua publishes an OpenAPI 3.1 specification that describes every endpoint, parameter, and response shape in this documentation. Use it to generate type-safe clients in any language, validate requests in your tests, and keep your integrations in lockstep with the API.

Where to get the spec

The spec is available in two forms:

Source	URL	Use case
Live API	https://api.akua.dev/v1/openapi.json	Always reflects the deployed API. Cache this for production codegen pipelines.
Static snapshot	docs/openapi-public.json	Versioned alongside the docs. Use for CI builds that need a stable input.

The two are kept in sync by Akua’s CI: every pull request that changes a public route must update docs/openapi-public.json or the build fails.

Generate a client

Most languages have mature OpenAPI codegen tooling. Pick whichever fits your stack:

TypeScript and JavaScript

openapi-typescript generates a single .d.ts file with no runtime dependencies. Pair it with openapi-fetch for a type-safe fetch wrapper.

# Generate types
npx openapi-typescript https://api.akua.dev/v1/openapi.json -o src/akua-api.d.ts

import createClient from 'openapi-fetch';
import type { paths } from './akua-api';

const client = createClient<paths>({
	baseUrl: 'https://api.akua.dev/v1',
	headers: {
		Authorization: `Bearer ${process.env.AKUA_API_TOKEN}`,
		// Optional — omit when using a workspace API token (workspace is implied).
		// Set only for broad credentials to select the target workspace.
		'Akua-Context': process.env.AKUA_WORKSPACE_ID
	}
});

const { data, error } = await client.GET('/installs/{id}', {
	params: { path: { id: 'j572abc123' } }
});

Go

The Akua CLI uses oapi-codegen to generate a strongly-typed Go client.

# Generate a client package
go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen \
	-package akua \
	-generate types,client \
	-o akua/client.gen.go \
	https://api.akua.dev/v1/openapi.json

Python

openapi-python-client emits a Pydantic-typed package.

pip install openapi-python-client
openapi-python-client generate --url https://api.akua.dev/v1/openapi.json

Other languages

The OpenAPI Generator project ships generators for 50+ languages, including Java, C#, Rust, PHP, and Ruby. The Akua spec is plain OpenAPI 3.1 with no vendor extensions, so any compliant generator works.

Versioning

The API path includes a version segment (/v1/...). Breaking changes ship under a new version path; the previous version stays available for at least 12 months after a new one launches.

Inside a version, Akua follows additive evolution:

• New endpoints and new optional fields can appear at any time.
• Existing fields are never removed or renamed within a version.
• Validation rules can tighten (rare; flagged in the changelog).

If your generated client compiled against an older spec snapshot, regenerating against a newer snapshot is always safe within the same major version.

Stay in sync

For CI pipelines that consume the spec, pin to the static snapshot file in this repository and bump it deliberately:

# Fail the build if the local copy drifts from upstream
curl -fsS https://raw.githubusercontent.com/cnap-tech/cnap/main/docs/openapi-public.json -o /tmp/upstream.json
diff -q /tmp/upstream.json ./vendor/akua-openapi.json

For long-running services, prefer the live URL with a short cache so new endpoints become available the moment they ship.

Related topics

Introduction

API base URL, conventions, and error envelope.

Authentication

Workspace API tokens and JWT auth.

CLI reference

The Akua CLI built on top of the same API.