> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAPI specification
> Download the spec, generate type-safe clients, and stay in sync with API changes
Akua publishes an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) 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`](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`](https://github.com/openapi-ts/openapi-typescript) generates a single `.d.ts` file with no runtime dependencies. Pair it with [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript) for a type-safe `fetch` wrapper.
```bash theme={null}
# 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
```
```ts theme={null}
import createClient from 'openapi-fetch';
import type { paths } from './akua-api';
const client = createClient({
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`](https://github.com/oapi-codegen/oapi-codegen) generates a strongly typed Go client.
```bash theme={null}
# 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`](https://github.com/openapi-generators/openapi-python-client) emits a Pydantic-typed package.
```bash theme={null}
pip install openapi-python-client
openapi-python-client generate --url https://api.akua.dev/v1/openapi.json
```
### Other languages
The [OpenAPI Generator](https://openapi-generator.tech/docs/generators) 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](/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:
```bash theme={null}
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:
```bash theme={null}
# 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
```
## Related topics
API base URL, conventions, and error envelope.
Workspace API tokens and JWT auth.
Discover and run commands generated from this contract.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.