Conventions
The conventions on this page are cross-cutting. Every endpoint in the Kilimanjaro API and every SDK method across the twelve languages obeys them; a reference page later in this hub that contradicts a clause here is a defect against the binding spec.
1. Response envelope
1.1 Success and failure shape
Every SDK method returns one of two outcomes: success delivering {data, meta}, or failure delivering a typed KError. The mode is single — there is no chainable .orThrow(), no safe() companion, no Result-and-also-throws hybrid.
The wire shape is uniform:
- Success. HTTP 2xx with body
{"data": <result>, "meta": <meta>}. Both fields are always present on success;metais non-null even when sparsely populated. - Failure. HTTP 4xx or 5xx with body
{"code": <SCREAMING_SNAKE_CASE>, "message": <human_readable>, "context": <object>, "recommendation": <text | null>}. The KError JSON shape is canonical across every endpoint, every SDK, every CLI invocation.
1.2 Per-language idiomatic delivery
The wire contract is identical across the twelve SDKs; the per-language shape is idiomatic.
- Throw-on-error. TypeScript / JavaScript, Python, Java, Kotlin, .NET, Swift, Ruby, PHP, Flutter / Dart, React Native. Method returns
Response<T>; failure throwsKError. Caller usestry / catchor the language-idiomatic equivalent. - Tuple return. Go. Method returns
(envelope, err), where the envelope carriesDataandMeta. Failure delivers a non-nil*KErrorinerr. - Result return. Rust. Method returns
Result<Response<T>, KError>. Failure isErr(KError).
The capability shape is binding; the per-language ergonomic expression is the SDK author's idiomatic call.
1.3 The meta envelope sub-shape
meta is structured as namespaces, not flat fields. Every sub-shape is a namespace — including dimensions that currently hold one field — so additions compose without breaking the wire shape.
Always-present namespaces:
| Namespace | Contents |
|---|---|
meta.cost | Six-dimensional cost attribution (governed operations, CPU-ms, storage GB-mo, egress GB, API calls, vault ops). Sparsely populated; only dimensions touched by the operation appear. |
meta.timing | Gateway latency, origin latency, total. |
meta.context | Operation context — request id, trace id, project id, shard id where relevant. |
Conditional namespaces (present when the surface produces them):
| Namespace | Fields | Surfaced on |
|---|---|---|
meta.cursor | next (opaque base64 cursor or null), totalCount (integer; present when count != 'none'), countMethod ("exact" or "estimated") | List endpoints |
meta.idempotency | key (the key used; auto-generated if not supplied), replayed (boolean — true when the response is a cached replay) | Mutating responses |
meta.warnings | Array of {code, message} objects | When warnings exist |
Warnings ride the success-path meta envelope; they are not errors. A warning communicates a soft signal — deprecation, count-mode downgrade, soft-quota approach — on a successful call. An error short-circuits the success path entirely and is delivered as a KError per §2.
meta is opt-in for non-cost namespaces via the X-Include-Meta request header. meta.cost is always populated when populated at all (it is the metering signal); other namespaces populate when requested.
2. KError
2.1 Shape
Every error delivered by the platform — at the SDK surface, on the wire, in the CLI's structured-output mode — is a KError:
{
"code": "STRING",
"message": "human-readable",
"context": { /* family-specific structured fields */ },
"recommendation": null // or remediation text when present
}
| Field | Type | Notes |
|---|---|---|
code | string (SCREAMING_SNAKE_CASE) | Drawn from a closed taxonomy. |
message | string | Human-readable; safe to log; safe to surface. |
context | object | Family-specific structured fields. |
recommendation | text | null | Optional remediation hint: text when present, usually null. |
The four fields are universal. Family-specific extensions live inside context; they never extend the top-level shape. A consumer that reads code, switches on its known family, and falls through to a generic handler for unknown codes handles every error the platform throws across both modules and all surfaces.
2.2 The closed-taxonomy rule
code is drawn from a closed taxonomy enumerated in the error catalogue. Adding a new code is an amendment to the catalogue, lifted into the SDK release that ships the new surface. Implementations may not coin private codes. A KError with a code not in the catalogue is a defect in the catalogue, not a license to extemporise.
2.3 Universal error families
Every surface introduces family-specific codes. The universal families that any endpoint may throw, paired with their canonical HTTP status codes per §9:
| Family | Examples | HTTP |
|---|---|---|
| Validation | K9O_INVALID_REQUEST_SHAPE, K9O_MISSING_REQUIRED_FIELD, K9O_INVALID_FIELD_VALUE | 400 |
| Auth | K9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED | 401 |
| Authorisation | K9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED | 403 |
| Resource | K9O_NOT_FOUND, K9O_ALREADY_EXISTS, K9O_STATE_CONFLICT | 404 / 409 |
| Tier / capacity | K9O_TIER_CAP_HIT, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED | 409 / 429 |
| Idempotency | K9O_IDEMPOTENCY_KEY_COLLISION | 409 |
| Anti-injection | K9O_INJECTION_DETECTED | 400 |
| Shard / data | K9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED | 422 |
| Custody | K9O_CUSTODY_MISMATCH | 409 |
| Gate | K9O_GATE_REQUIRED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_ALREADY_REDEEMED, K9O_GATE_CONSTRAINT_VIOLATION | 403 / 409 / 422 |
| Server | K9O_INTERNAL_ERROR, K9O_UPSTREAM_UNAVAILABLE | 5xx |
2.4 The recommendation field
recommendation is optional and is null on most errors. A consumer that ignores recommendation still gets a complete and actionable error from code + message + context. recommendation is the assistive payload: when set, it is text. Always handle it as possibly null.
3. Naming and casing
3.1 Wire format
| Surface | Casing | Example |
|---|---|---|
| JSON object keys | camelCase | {"projectId": "proj_kQ3pZ9rL2sW8"} |
| Enum values | SCREAMING_SNAKE_CASE | {"role": "PROJECT_ADMIN"} |
| URL path segments | kebab-case | /@shop/extension-permissions |
| Path vs query | Path-segments name resources; query-strings carry filters and pagination | limit, cursor, count are query params; the resource ID is in the path |
3.2 Resource identifier shape
Every persistent resource carries a Stripe-style identifier: <noun>_<12-char base62>. The 12-char base62 namespace covers ~3.2 × 10²¹ values.
| Prefix | Resource |
|---|---|
org_ | Organization |
proj_ | Project (= tenant) |
usr_ | User identity |
tok_ | Service token |
key_ | Kibo key reference |
apr_ | Approval (irreversible-action gate) |
wp_ | Governed Operation |
ext_ | Extension installation |
hs_ | Extension hook secret |
req_ | Request correlation id |
evt_ | Event (audit log entry, subscription mutation) |
eu_ | Project-level end-user identity |
IDs are immutable from creation. Ad-hoc prefix coining at SDK surfaces is a defect.
3.3 URL-prefix elision rule
Resource identifiers in URL paths drop the noun prefix. Everywhere else — request bodies, response payloads, log lines, audit ledgers, KError.context, schema names, the Console, CLI structured output — the prefix is part of the canonical ID.
| Surface | Form |
|---|---|
| Request URL path | Bare ID: /@shop/gates/kQ3pZ9rL2sW8 |
| Everywhere else | Prefixed ID: apr_kQ3pZ9rL2sW8 |
The elision applies to sub-resource identifiers that appear in URL paths (gates, governed operations, extensions, hook secrets, audit events, end-users, and so on). Org and project context are not addressed by ID at all in customer-facing URLs — the org slug is carried in the subdomain and the project slug at path position 1 (the @<projectSlug> marker); see Slug addressing.
SDK input policy: methods that take a sub-resource ID accept both forms — the prefixed (apr_kQ3pZ9rL2sW8) and the bare (kQ3pZ9rL2sW8). The SDK normalises to prefixed internally and serialises to prefixed on output; the URL builder strips the prefix at path-construction time.
3.4 Per-language casing
The wire format is camelCase; per-language SDK surfaces translate to the language idiom. Summary:
| Surface | TS / JS, Java, Kotlin, .NET, Swift, Flutter, RN | Python, Ruby, PHP | Go | Rust |
|---|---|---|---|---|
| Method names | camelCase | snake_case | PascalCase | snake_case |
| Type names | PascalCase | PascalCase | PascalCase | PascalCase |
| Constants and enum values | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE |
| Field names on data objects | Matches method-name casing | Matches method-name casing | Matches method-name casing | Matches method-name casing |
The wire-format ↔ language-format mapping is mechanical and codegen-driven. SDKs do not introduce per-method per-language naming exceptions.
3.5 No nominal-typing factories
No factory functions where strings work. client.from("users") over client.from(Tables.Users). The SDK accepts strings for collection names, table names, function names, role names, custody-mode names. Codegen-time type-checking across these strings is achieved through the per-language typed-codegen pipeline (TypeScript template literal types, Python typing.Literal), not through nominal factory functions.
4. HTTP method semantics
| Method | Use | Idempotent? | Body |
|---|---|---|---|
GET | Read; never mutates | Yes | None on request; JSON on response |
POST | Create; or invoke a non-idempotent action | Conditionally (see §7) | JSON on both |
PATCH | Partial update | Conditionally | JSON on both |
PUT | Full replace; or upsert | Conditionally | JSON on both |
DELETE | Delete | Yes (re-delete is no-op or K9O_NOT_FOUND per surface) | None on request; JSON on response |
The platform does not use POST for read-side operations except where the read is logically a query the URL cannot carry — complex search payloads in the data pillar's SQL surface, for instance. Where this exception applies, the surface reference page calls it out.
PUT semantics: full-replace on the addressed resource. Upsert (create-or-replace by client-supplied ID) is documented per surface. The default verb for upsert is PUT; the default verb for partial mutation is PATCH.
5. Versioning
5.1 URL grammar and API version
The URL carries tenancy. SDKs also send a K9o-API-Version header.
https://<orgSlug>.api.k9o.io/@<projectSlug>/<sub-resource>/...
The subdomain (<orgSlug>) is the org-context anchor. The @-prefix at path position 1 is the project-context marker. The remainder of the path is the surface — data, gate, functions, kibo, and so on. Platform-bound surfaces that are not tenant-scoped (anonymous discovery, operator sign-up, platform health) live at the root host api.k9o.io. See Slug addressing for org and project slug rules, and Routing modes for the three deploy-time routing modes (subdomain Cloud default + path-prefix LAN multi-tenant + single-org Private Perimeter appliance) the grammar maps onto.
The K9o-API-Version header is accepted on every request and the SDKs send it with their release version, but the gateway does not select a surface from it: it is informational, and you cannot pin an API version with it.
SDK base-URL config. SDKs construct against <orgSlug>.api.k9o.io by default — the org slug is the SDK init argument; the path @<projectSlug> segment is composed by the SDK's URL builder per call site. SDKs emit the K9o-API-Version header on every request, set to the SDK's release. SDKs expose a baseUrl override for self-managed, LAN-routed, and air-gapped deployments — the override accepts the host portion only (e.g., https://kilimanjaro.acme.local), and the SDK composes <orgSlug> and @<projectSlug> per the gateway's configured routing mode. A baseUrl override that includes a path segment beyond the host throws K9O_INVALID_BASE_URL at SDK initialisation.
5.2 Minor and patch versioning
Within v2, minor and patch changes are non-breaking by definition:
| Change class | Definition |
|---|---|
| Patch | Bug-fixes; no surface change. |
| Minor | New optional fields on requests, new fields in meta, new endpoints, new error codes that strictly add to the closed taxonomy. |
| Major (v3) | Breaks an existing v2 caller (removing a field, changing a code's semantics, requiring a previously-optional field). |
The CLI exposes the active gateway minor version via k9o version; SDK packages publish minor and patch in their package version per language idiom (npm semver, PyPI version, Cargo).
5.3 Deprecation surface
A v2 surface may be marked deprecated mid-lifetime. Deprecated surfaces continue to work (deprecation is not removal) and surface a warning in meta.warnings, as a {code, message} entry that names the replacement and the version that removes the surface.
meta.warnings is always populated when warnings exist and absent otherwise; consumers that iterate the array handle deprecation warnings by virtue of normal iteration.
6. Pagination
6.1 Cursor-based, opaque
All list endpoints use cursor-based pagination. Cursor-based pagination is stable under writes — a record inserted between page fetches does not shift the offset of subsequent pages — and scales without server-side row-counting. Offset-based pagination is not supported. Total counts are opt-in via the count query parameter (§6.4).
6.2 Wire shape
Request.
GET https://<orgSlug>.api.k9o.io/@<projectSlug>/<resource>?limit=<n>&cursor=<token>&count=<mode>
| Parameter | Type | Notes |
|---|---|---|
limit | integer | Between 1 and the per-surface max. Default 50; max 1000 unless a surface pins it lower. |
cursor | opaque base64 token | Returned in meta.cursor.next of a prior response. Absent on the first page. |
count | enum | none (default), exact, or estimated. See §6.4. |
| filter params | per surface | Documented in the surface's reference page. |
Response.
{
"data": [ /* items */ ],
"meta": {
"cursor": {
"next": "<token-or-null>",
"totalCount": 1234,
"countMethod": "exact"
}
}
}
datais the array of items; never null on success;[]is valid (empty page).meta.cursor.nextis the token to fetch the next page;nullindicates the final page.meta.cursor.totalCountandmeta.cursor.countMethodare present when the caller requested (or the server downgraded into) a count mode other thannone.
6.3 Cursor lifetime
Cursors are valid for 24 hours from issuance. Beyond that, a cursor returns K9O_INVALID_CURSOR (HTTP 400); the caller restarts pagination from the beginning. Cursor opacity is binding: callers must not parse cursors, and the platform may change the cursor's internal representation without notice in any minor or patch release.
A cursor is bound to its issuing query parameters. Re-using a cursor against an endpoint with different filter parameters returns K9O_INVALID_CURSOR.
6.4 Opt-in counts
Total-row counts are opt-in via the count query parameter, not delivered by default.
count value | Behaviour | Cost |
|---|---|---|
none (default) | No count returned. meta.cursor.totalCount and meta.cursor.countMethod are not present. | Zero. |
exact | Server runs COUNT(*) matching the query filters. Returns meta.cursor.totalCount: <n> and meta.cursor.countMethod: "exact". | Scan over matching rows; non-trivial at large set size. |
estimated | Server returns a pg_class.reltuples-style estimate. Returns meta.cursor.totalCount: <n> and meta.cursor.countMethod: "estimated". | Constant-time; stale by however long since the last ANALYZE. |
Downgrade pattern. When a caller requests a count mode the server cannot deliver at acceptable cost (for example exact over a very large result set), the server does not reject. It demotes to the cheapest adequate mode (estimated), returns the data, and emits a K9O_COUNT_MODE_DOWNGRADED entry in meta.warnings naming the requested mode and the delivered mode. The downgrade pattern is generic — if further count modes are introduced, the same demote-and-warn rule applies.
7. Retry and idempotency
7.1 What's retryable
The SDK auto-retries the following categories by default:
- 5xx server errors.
K9O_INTERNAL_ERROR,K9O_UPSTREAM_UNAVAILABLE, the surface-specific 503 dependency-unreachable and 504 upstream-timeout codes, plus any unmapped 5xx. - 429 capacity errors.
K9O_TIER_RATE_LIMIT_EXCEEDED,K9O_POOL_EXHAUSTED,K9O_RATE_LIMITED.Retry-Afteris honoured. - Network errors. Connection reset, DNS failure, request timeout.
The SDK does not auto-retry the following:
- 4xx (except 429). Validation, auth, authorisation, resource, idempotency-collision, custody errors. These are caller-actionable; auto-retry masks the bug.
K9O_TIER_CAP_HIT(409). Raising the cap (enabling Headroom or adding usage) is the action, not retry.
7.2 Backoff
Exponential backoff with full jitter. Default policy:
| Setting | Default |
|---|---|
| Base delay | 100 ms |
| Multiplier | 2.0 per attempt |
| Jitter | full (uniform random in [0, base × multiplier^attempt]) |
| Max attempts | 5 (initial + 4 retries) |
| Max total wall-clock | 30 s |
The Retry-After header on 429 (and on 5xx where surfaced) overrides the computed backoff for that attempt.
7.3 RetryConfig SDK option
The TypeScript SDK takes a retryConfig on the client constructor:
import { createClient } from '@k9o/core';
const client = createClient({
orgSlug: '<orgSlug>',
projectSlug: '<projectSlug>',
apiKey: process.env.K9O_API_KEY,
retryConfig: {
maxRetries: 5,
backoff: 'exponential', // 'exponential' | 'linear' | 'none'
initialDelayMs: 100,
maxDelayMs: 5000,
},
});
Retries cover idempotent methods only (GET, HEAD, OPTIONS, DELETE), on network failure and on HTTP 429, 502, 503 and 504.
7.4 Idempotency keys
Every mutating SDK method accepts { idempotencyKey: string } as a top-level option. Generic across the SDK; not nested in a requestOptions field; cross-language; parameter name matches per-language casing.
The SDK auto-generates an idempotency key (UUID v4) for every mutating call when the caller does not supply one. The auto-generated key surfaces in meta.idempotency.key on the response, alongside meta.idempotency.replayed: false for fresh executions.
The wire-side equivalent of the SDK option is the Idempotency-Key header. Either the SDK option or the header sets the key; if both are set and disagree, the SDK throws K9O_INVALID_REQUEST_SHAPE at construct time before the request leaves the client.
Read methods (GET) do not accept idempotency keys. Reads are naturally idempotent; the option is rejected at compile time in statically-typed languages and at runtime via K9O_INVALID_REQUEST_SHAPE in dynamic languages.
7.5 Collision semantics
The platform follows replay-with-strict-match:
| Scenario | Behaviour |
|---|---|
| Key not seen within TTL | Treat as fresh request; execute; record the key + request hash + response in the idempotency log. Response carries meta.idempotency.replayed: false. |
| Key seen + request hash matches | Return cached response from log; do not re-execute. Response carries meta.idempotency.replayed: true. The replayed call is one operation, not two — metering attributes the dedupe. |
| Key seen + request hash mismatches | Throw K9O_IDEMPOTENCY_KEY_COLLISION (HTTP 409). KError.context carries previousRequestHash, currentRequestHash, previousResponseTimestamp. The caller fixes the bug or rotates the key. |
| Key seen + outside TTL | Treat as fresh request; the prior log entry has expired. Response carries meta.idempotency.replayed: false. |
The collision case throws by design. Silent replay-of-cached-response when the body has changed would mask real bugs (a buggy retry that mutated the body would receive the original response unaware). Strict-match preserves the principal use case — network-failure retry where the body is identical by definition — and catches the buggy-retry footgun.
Body hash. SHA-256 over canonical-JSON-serialised request body, excluding the idempotencyKey field itself. The canonical-JSON serialiser lives in the gateway, not the SDK, so the comparison is stable across all twelve SDKs.
TTL. 24 hours from first execution, flat for every project.
Cross-project collisions are impossible by construction. Two requests with the same idempotency key in different projects address two different project schemas. This is load-bearing under agent workloads where deterministic key generation ("encrypt-customer-123-credit-card-2026-05-01") is more common than UUID v4 and cross-project key reuse is a reasonable expectation.
7.6 Retry × idempotency interaction
The two mechanisms compose:
- The SDK auto-generates an idempotency key on every mutating call.
- On retry-eligible failure, the SDK retries the same call with the same idempotency key.
- The gateway dedupes via the idempotency log.
- Net effect: a network-failure retry of a write either replays the cached response (if the first attempt reached the gateway) or executes once (if it did not); the caller sees one successful response or one error, never two side effects.
8. Headers
8.1 Standard request headers
| Header | Required | Purpose |
|---|---|---|
Authorization: Bearer <token> | Yes (except boot endpoints) | Auth token. User tokens are user-scoped; service tokens are project-scoped. |
Content-Type: application/json; charset=utf-8 | On request bodies | JSON wire format. Multipart uses multipart/form-data for storage uploads. |
X-K9o-Project: <proj_id> | Conditionally | Establishes the project context for user-scoped tokens. Service tokens carry the project in the token; the header is redundant and (if present) must match or K9O_PROJECT_SCOPE_MISMATCH (HTTP 403) is thrown. |
Idempotency-Key: <key> | Optional | Wire-side equivalent of the SDK idempotencyKey option. |
X-Include-Meta: <token-list> | Optional | Selects which meta sub-shapes the response includes. |
X-K9o-Trace-Id: <id> | Optional | Caller-supplied trace correlator; surfaced in meta.context.traceId. Auto-generated if absent. |
Retry-After: <seconds> | Server-supplied on 429 / some 5xx | Honoured by SDK auto-retry. |
8.2 Standard response headers
Every response includes:
| Header | Notes |
|---|---|
X-K9o-Request-Id: req_<12-char base62> | Per-request correlator. Always populated. |
X-K9o-Trace-Id: <id> | Echoes the caller-supplied trace id, or the auto-generated one. |
Content-Type: application/json; charset=utf-8 | Except where the surface returns a non-JSON payload (storage signed-URL responses). |
5xx and 429 responses additionally include Retry-After.
8.3 Project-context resolution
The platform resolves the project context per request in two layers:
Source precedence — order:
- URL
@<projectSlug>marker at path position 1 (/@<projectSlug>/...). When the path opens with the@-prefix project marker, that slug is the authoritative project context. The gateway resolves slug to ID againstk9o_platform.slug_reservationper Slug addressing. X-K9o-Projectheader. When no@<projectSlug>marker is present, the gateway reads this header. Accepts either prefixed (proj_<base62>) or slug form.- Token
proj_idclaim. Fallback when neither URL marker nor header is present (service tokens carry the bound project in the token).
If the URL marker identifies project A and the header/claim identifies project B, the URL wins and the header/claim is ignored for project-context resolution. The gateway validates that the calling token has access to the URL-identified project.
Org context is resolved orthogonally — the org slug carried in the subdomain under subdomain routing mode, in the path position-1 segment under path-prefix routing mode, and from K9O_DEFAULT_ORG under single-org routing mode. See Routing modes.
Token-class checks (applied after the source precedence has resolved the project identifier):
- Service token presented. The token's bound project must match the resolved project context. Mismatch throws
K9O_PROJECT_SCOPE_MISMATCH(HTTP 403). - User token presented. The platform validates the user has membership in the resolved project's organisation and the requested role. If a user token is presented and no project context can be resolved, the request must target an org-scoped or pre-project endpoint; project-scoped operations under these conditions throw
K9O_MISSING_PROJECT_CONTEXT(HTTP 400). - Org-scoped operations. Accept user tokens without project context; an
X-K9o-Projectheader on these calls is ignored.
The resolution rule is binding across every surface. Each endpoint's reference page assumes the project context is established by the time the endpoint's logic runs.
8.4 Anonymous-bypass paths
The following paths bypass JWT verification at the gateway. All other paths require a valid bearer or service token.
| Path | Method(s) | Rationale |
|---|---|---|
/@<projectSlug>/auth/jwks (on <orgSlug>.api.k9o.io) | GET | Public per-project JWKS; consumers verify JWTs with this key without holding a token. |
/auth/jwks (on <orgSlug>.api.k9o.io) | GET | Org-scoped JWKS — same rationale; org tokens verified by customers' own services. |
/extensions/jwks (on api.k9o.io root host) | GET | Gateway hook-signing public key; extensions verify the gateway-signed JWT on inbound webhook deliveries. |
/healthz (on api.k9o.io root host) | GET | Platform health probe; reachable from infrastructure monitoring without credentials. |
Sign-in and other pre-project mutations are not on this list. They are unauthenticated at the application layer (no token presented because none yet exists) but pass through the standard middleware pipeline and are subject to per-IP rate limiting; the path is not bypassed.
9. Status code mapping
Canonical mapping between HTTP status codes and the KError family. A status code that does not appear here is not used by the platform.
| Status | Meaning | KError families |
|---|---|---|
| 200 | OK; success with body | n/a (success path) |
| 201 | Created; success on resource creation | n/a |
| 202 | Accepted; asynchronous work in progress | n/a |
| 204 | No content; success on resource deletion | n/a |
| 400 | Validation, malformed request, anti-injection rejection at edge | K9O_INVALID_REQUEST_SHAPE, K9O_MISSING_REQUIRED_FIELD, K9O_INVALID_FIELD_VALUE, K9O_INVALID_CURSOR, K9O_INJECTION_DETECTED, K9O_MISSING_PROJECT_CONTEXT, K9O_MISSING_API_VERSION, K9O_INVALID_API_VERSION |
| 401 | Auth missing or invalid | K9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED |
| 403 | Authorisation denied | K9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED, K9O_GATE_REQUIRED |
| 404 | Resource not found | K9O_NOT_FOUND (resource-qualified per surface — e.g. K9O_SECRET_NOT_FOUND) |
| 409 | State conflict; capacity cap; irreversible-gate conflict | K9O_ALREADY_EXISTS, K9O_STATE_CONFLICT, K9O_IDEMPOTENCY_KEY_COLLISION, K9O_CUSTODY_MISMATCH, K9O_TIER_CAP_HIT, K9O_GATE_ALREADY_REDEEMED |
| 422 | Semantically valid but operation rejected | K9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_CONSTRAINT_VIOLATION |
| 429 | Capacity / rate limit | K9O_RATE_LIMITED, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED |
| 500 | Internal server error | K9O_INTERNAL_ERROR |
| 502 | Upstream unavailable | K9O_UPSTREAM_UNAVAILABLE |
| 503 | Dependency unavailable; service temporarily down | surface-specific (e.g. K9O_BYOK_KEY_UNREACHABLE, K9O_HYOK_CLUSTER_UNREACHABLE, K9O_EXTENSION_DISABLED) |
| 504 | Upstream timeout | surface-specific (e.g. K9O_FUNCTION_TIMEOUT, K9O_EXTENSION_HOOK_TIMEOUT) |
10. Wire format
10.1 JSON (default)
Request and response bodies are JSON encoded UTF-8 (Content-Type: application/json; charset=utf-8). The platform does not negotiate other formats via Accept headers; an unsupported Accept returns 406 with body {"code": "UNSUPPORTED_MEDIA_TYPE", ...}.
| Element | Format |
|---|---|
| Integers | Up to 2⁵³−1 are safe across every SDK. Larger integers (e.g., nanosecond timestamps in the data pillar's subscription primitive) surface as decimal strings, with the affected fields documented per surface. |
| Timestamps | ISO 8601 with millisecond precision, UTC, Z suffix: "2026-05-01T12:34:56.789Z". The platform does not surface non-UTC timestamps on the wire. |
10.2 Multipart (storage surfaces)
The storage primitive uses multipart/form-data for direct binary uploads; the metadata envelope and the binary stream travel together. Storage downloads use signed URLs returned in JSON; the binary itself is fetched from the signed URL with application/octet-stream and is opaque to the platform.
10.3 Streaming (surface-specific)
Subscriptions (data pillar) and function-stream (compute pillar) are the two streaming surfaces. The wire-protocol choice is specified in the surface's reference page; the async-iterator SDK contract is language-idiom-agnostic and does not surface the wire choice in the SDK API.
10.4 CLI structured-output mode
The CLI's machine-readable mode emits KError and success responses in the same JSON wire shape as the API. A CLI command that fails writes the KError JSON to stderr and exits with a non-zero status code per the CLI exit-code map; the JSON shape is the SDK's KError shape verbatim.
11. SDK packages
11.1 Catalogue
The SDK ships as a small set of packages with semantically-distinct namespaces:
| Package | Surface |
|---|---|
@k9o/core | Data + Compute + Control + Extensions. Entry-point for Native-mode customers running on Kilimanjaro. Peer-depends on @k9o/kibo and @k9o/gate and re-exports their primary symbols. |
@k9o/kibo | Kibo vault operations — key custody, custody-mode descents, BYOK / HYOK lifecycle. Standalone, or composed via @k9o/core. |
@k9o/gate | Gate (Identity-Aware Kernel) — session lifecycle, passwordless, social / OIDC, passkeys, MFA, password management, user management, transactional email / SMS, admin operations, SAML / SCIM / IdP federation. Standalone, or composed via @k9o/core. |
The catalogue is closed — extension-class packages (@k9o/<extension-name>, e.g., @k9o/gate-studio) ship via the extension-manifest path, not as core SDK packages.
11.2 Dual-import-path convention
Each capability namespace is reachable two ways:
// Standalone import — pulls only the capability; no peer-dep on the rest of the platform.
import { configureGate, gate } from '@k9o/gate';
configureGate({ mode: 'standalone', projectSlug: '<projectSlug>', baseUrl: 'https://<orgSlug>.api.k9o.io' });
await gate.signUp({ email, password });
// Composed import — one client; capability namespaces hang off it.
import { createClient } from '@k9o/core';
const client = createClient({ orgSlug: '<orgSlug>', projectSlug: '<projectSlug>', apiKey: process.env.K9O_API_KEY });
await client.gate.signUp({ email, password });
Both forms reach the same Gate surface. @k9o/core lists @k9o/kibo and @k9o/gate as peer-dependencies and exposes them as client.gate and client.kibo. Standalone customers install only the capability package they need; Native-mode customers install @k9o/core, which transitively requires the composed capabilities.
The standalone-import path is the entry for customers who pick a single capability — adopt @k9o/gate to replace an existing identity provider without committing to the rest of the platform; adopt @k9o/kibo to use the vault layer against an existing data plane.
11.3 Namespace shape
SDK namespaces follow a closed-taxonomy rule analogous to §2.2 (KError) and §3.2 (resource prefixes):
| Level | Examples | Discipline |
|---|---|---|
| Top-level entry namespaces | from, gate, kibo, functions, extensions | Reserved for capability-level entry points. Catalogue closed; extends only via amendment. |
| Category sub-namespaces | gate.passwordless.*, gate.identityProviders.*, kibo.byok.* | Group related functions inside a capability. Per-capability catalogues declared in the chapter that owns the capability. |
| Marquee primitives | gate.signUp, gate.signIn, gate.whoami | Flat at the capability root for discoverability. Categorised operations sit below. |
| Function names | camelCase per §3.4 | Closed per-capability. Ad-hoc surface coining at SDK build time is a defect. |
The SDK surface is consumed verbatim across the twelve languages per §1.2; the per-language shape (snake_case in Python / Ruby / PHP; PascalCase methods in Go) is mechanical codegen.