akua api

Shipped

Call the hosted Akua API from the OSS CLI. This is an optional hosted extension: local package workflows such as render, export, check, lint, test, and verify do not require hosted API credentials or network access.

akua api <path-or-url> [flags]
akua api spec [--audience=<public|partner|admin|internal>] [flags]

<path-or-url> can be a version-relative path such as /workspaces or an absolute URL on the configured API origin. Relative paths are resolved under the base URL. The default base URL is https://api.akua.dev/v1/.

Examples

# List workspaces
akua api /workspaces

# Create a product from a JSON body
akua api /products -X POST --input product.json

# Send typed fields as JSON
akua api /access_decisions -X POST -F permission=offers.create

# Send a workspace context header
akua api /products --workspace ws_123

# Fetch the public OpenAPI document
akua api spec

# Use a non-default API origin
akua api /workspaces --base-url https://staging.example.dev/v1/

Request flags

flag	description
`-X, --method=<method>`	HTTP method. Defaults to `GET` when no body or fields are present, otherwise `POST`
`-H, --header=<name:value>`	extra request header. `name=value` is also accepted
`-f, --raw-field=<key=value>`	string field. Sent as query params for read methods and JSON body fields for writes without `--input`; when `--input` is present, fields stay in the query string
`-F, --field=<key=value>`	typed field. Parses `true`, `false`, `null`, and integers before sending
`--input=<file>`	JSON file to use as the request body
`--jq=<expr>`	reserved for response filtering; currently returns `E_UNSUPPORTED`
`--include`	reserved for response-header output; currently returns `E_UNSUPPORTED`
`--silent`	suppress a successful response body
`--paginate`	reserved for pagination; currently returns `E_UNSUPPORTED`
`--slurp`	reserved for paginated response aggregation; currently returns `E_UNSUPPORTED`

Connection flags

flag	description
`--base-url=<url>`	hosted API base URL. Defaults to `https://api.akua.dev/v1/`
`--token=<token>`	bearer token for hosted API auth
`--workspace=<id>`	workspace context sent as the `akua-context` request header

Environment resolution

Connection values resolve in this order:

setting	resolution
base URL	`--base-url`, then `AKUA_API_BASE_URL`, then `https://api.akua.dev/v1/`
bearer token	`--token`, then `AKUA_API_TOKEN`
workspace context	`--workspace`, then `AKUA_WORKSPACE_ID`

akua api uses hosted API bearer tokens only. akua auth remains registry auth for OCI operations and is not reused for hosted API requests. A missing hosted API token fails with E_AUTH_REQUIRED; pass --token or set AKUA_API_TOKEN.

`akua api spec`

akua api spec fetches the public OpenAPI document from /openapi.json on the configured base URL. akua api spec --audience public is equivalent.

Elevated audiences are visible in the CLI contract but not served in this release:

akua api spec --audience partner
akua api spec --audience admin
akua api spec --audience internal

Each elevated audience exits with E_UNSUPPORTED until the hosted API serves authorized audience-specific OpenAPI documents. The CLI does not locally filter the public OpenAPI document to simulate elevated audiences.

Structured errors

Failed hosted API calls emit Akua structured errors on stderr. Under --json or agent context, stderr is JSON-lines:

{"code":"E_AUTH_INVALID","message":"token is invalid or expired","docs":"https://akua.dev/errors/E_AUTH_INVALID"}

HTTP 401 maps to auth errors, 403 maps to forbidden user errors, 429 exits with the rate-limited exit code, and transport/timeouts use the standard CLI contract exit codes.

Exit codes

0 success, 1 user error, 2 system error, 4 rate limited, 6 timeout.