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 canonical public OpenAPI document is always available at: https://api.akua.dev/v1/openapi.json Use that URL for downloads, codegen, and production pipelines. It always reflects the deployed public API. For CI builds that must pin to a stable input (instead of fetching the live document), you can optionally vendor a snapshot of the same public spec from this repository’s docs/openapi-public.json. Akua’s CI keeps that file in sync: every pull request that changes a public route must update it or the build fails. Prefer the live URL unless you specifically need a pinned checksum.

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.

# Install a reviewed exact version, then generate types without network fallback
bun add --dev --exact openapi-typescript@7.13.0
bun node_modules/openapi-typescript/bin/cli.js 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 most consumers, fetch the live public document and cache it briefly so new endpoints become available as soon as they ship:

curl -fsS https://api.akua.dev/v1/openapi.json -o ./vendor/akua-openapi.json

If your CI must pin to a checksummed snapshot instead, vendor docs/openapi-public.json from this repository and bump it deliberately:

# Fail the build if the local copy drifts from the optional repo snapshot
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

Introduction

API base URL, conventions, and error envelope.

Authentication

Workspace API tokens and JWT auth.

CLI

Discover and run commands generated from this contract.

Overview

Endpoints

Where to get the spec

Generate a client

TypeScript and JavaScript

Go

Python

Other languages

Versioning

Stay in sync

Introduction

Authentication

CLI

​Where to get the spec

​Generate a client

​TypeScript and JavaScript

​Go

​Python

​Other languages

​Versioning

​Stay in sync

​Related topics

Introduction

Authentication

CLI

Where to get the spec

Generate a client

TypeScript and JavaScript

Go

Python

Other languages

Versioning

Stay in sync

Related topics