OpenAPI specification

The OpenAPI 3.1 spec lists endpoints and typed request and response schemas, then generates type-safe clients for TypeScript, Go, and Python

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

oapi-codegen generates 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/akua-dev/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.

Introduction

API base URL, conventions, and error envelope.

Authentication

Workspace API tokens and JWT auth.

CLI preview

Akua CLI status and supported automation alternatives.

Overview

Endpoints

Where to get the spec

Generate a client

TypeScript and JavaScript

Go

Python

Other languages

Versioning

Stay in sync

Introduction

Authentication

CLI preview

​Where to get the spec

​Generate a client

​TypeScript and JavaScript

​Go

​Python

​Other languages

​Versioning

​Stay in sync

​Related topics

Introduction

Authentication

CLI preview

Where to get the spec

Generate a client

TypeScript and JavaScript

Go

Python

Other languages

Versioning

Stay in sync

Related topics