> ## 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 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`](https://github.com/akua-dev/cnap/blob/main/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`](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}
# Generate types
npx openapi-typescript 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 CI pipelines that consume the spec, pin to the static snapshot file in this repository and bump it deliberately:
```bash theme={null}
# 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.
## Related topics
API base URL, conventions, and error envelope.
Workspace API tokens and JWT auth.
Akua CLI status and supported automation alternatives.