Skip to main content

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; meta is 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 throws KError. Caller uses try / catch or the language-idiomatic equivalent.
  • Tuple return. Go. Method returns (envelope, err), where the envelope carries Data and Meta. Failure delivers a non-nil *KError in err.
  • Result return. Rust. Method returns Result<Response<T>, KError>. Failure is Err(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:

NamespaceContents
meta.costSix-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.timingGateway latency, origin latency, total.
meta.contextOperation context — request id, trace id, project id, shard id where relevant.

Conditional namespaces (present when the surface produces them):

NamespaceFieldsSurfaced on
meta.cursornext (opaque base64 cursor or null), totalCount (integer; present when count != 'none'), countMethod ("exact" or "estimated")List endpoints
meta.idempotencykey (the key used; auto-generated if not supplied), replayed (boolean — true when the response is a cached replay)Mutating responses
meta.warningsArray of {code, message} objectsWhen 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
}
FieldTypeNotes
codestring (SCREAMING_SNAKE_CASE)Drawn from a closed taxonomy.
messagestringHuman-readable; safe to log; safe to surface.
contextobjectFamily-specific structured fields.
recommendationtext | nullOptional 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:

FamilyExamplesHTTP
ValidationK9O_INVALID_REQUEST_SHAPE, K9O_MISSING_REQUIRED_FIELD, K9O_INVALID_FIELD_VALUE400
AuthK9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED401
AuthorisationK9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED403
ResourceK9O_NOT_FOUND, K9O_ALREADY_EXISTS, K9O_STATE_CONFLICT404 / 409
Tier / capacityK9O_TIER_CAP_HIT, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED409 / 429
IdempotencyK9O_IDEMPOTENCY_KEY_COLLISION409
Anti-injectionK9O_INJECTION_DETECTED400
Shard / dataK9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED422
CustodyK9O_CUSTODY_MISMATCH409
GateK9O_GATE_REQUIRED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_ALREADY_REDEEMED, K9O_GATE_CONSTRAINT_VIOLATION403 / 409 / 422
ServerK9O_INTERNAL_ERROR, K9O_UPSTREAM_UNAVAILABLE5xx

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​

SurfaceCasingExample
JSON object keyscamelCase{"projectId": "proj_kQ3pZ9rL2sW8"}
Enum valuesSCREAMING_SNAKE_CASE{"role": "PROJECT_ADMIN"}
URL path segmentskebab-case/@shop/extension-permissions
Path vs queryPath-segments name resources; query-strings carry filters and paginationlimit, 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.

PrefixResource
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.

SurfaceForm
Request URL pathBare ID: /@shop/gates/kQ3pZ9rL2sW8
Everywhere elsePrefixed 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:

SurfaceTS / JS, Java, Kotlin, .NET, Swift, Flutter, RNPython, Ruby, PHPGoRust
Method namescamelCasesnake_casePascalCasesnake_case
Type namesPascalCasePascalCasePascalCasePascalCase
Constants and enum valuesSCREAMING_SNAKE_CASESCREAMING_SNAKE_CASESCREAMING_SNAKE_CASESCREAMING_SNAKE_CASE
Field names on data objectsMatches method-name casingMatches method-name casingMatches method-name casingMatches 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​

MethodUseIdempotent?Body
GETRead; never mutatesYesNone on request; JSON on response
POSTCreate; or invoke a non-idempotent actionConditionally (see §7)JSON on both
PATCHPartial updateConditionallyJSON on both
PUTFull replace; or upsertConditionallyJSON on both
DELETEDeleteYes (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 classDefinition
PatchBug-fixes; no surface change.
MinorNew 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>
ParameterTypeNotes
limitintegerBetween 1 and the per-surface max. Default 50; max 1000 unless a surface pins it lower.
cursoropaque base64 tokenReturned in meta.cursor.next of a prior response. Absent on the first page.
countenumnone (default), exact, or estimated. See §6.4.
filter paramsper surfaceDocumented in the surface's reference page.

Response.

{
"data": [ /* items */ ],
"meta": {
"cursor": {
"next": "<token-or-null>",
"totalCount": 1234,
"countMethod": "exact"
}
}
}
  • data is the array of items; never null on success; [] is valid (empty page).
  • meta.cursor.next is the token to fetch the next page; null indicates the final page.
  • meta.cursor.totalCount and meta.cursor.countMethod are present when the caller requested (or the server downgraded into) a count mode other than none.

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 valueBehaviourCost
none (default)No count returned. meta.cursor.totalCount and meta.cursor.countMethod are not present.Zero.
exactServer 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.
estimatedServer 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-After is 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:

SettingDefault
Base delay100 ms
Multiplier2.0 per attempt
Jitterfull (uniform random in [0, base × multiplier^attempt])
Max attempts5 (initial + 4 retries)
Max total wall-clock30 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:

ScenarioBehaviour
Key not seen within TTLTreat as fresh request; execute; record the key + request hash + response in the idempotency log. Response carries meta.idempotency.replayed: false.
Key seen + request hash matchesReturn 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 mismatchesThrow K9O_IDEMPOTENCY_KEY_COLLISION (HTTP 409). KError.context carries previousRequestHash, currentRequestHash, previousResponseTimestamp. The caller fixes the bug or rotates the key.
Key seen + outside TTLTreat 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:

  1. The SDK auto-generates an idempotency key on every mutating call.
  2. On retry-eligible failure, the SDK retries the same call with the same idempotency key.
  3. The gateway dedupes via the idempotency log.
  4. 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​

HeaderRequiredPurpose
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-8On request bodiesJSON wire format. Multipart uses multipart/form-data for storage uploads.
X-K9o-Project: <proj_id>ConditionallyEstablishes 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>OptionalWire-side equivalent of the SDK idempotencyKey option.
X-Include-Meta: <token-list>OptionalSelects which meta sub-shapes the response includes.
X-K9o-Trace-Id: <id>OptionalCaller-supplied trace correlator; surfaced in meta.context.traceId. Auto-generated if absent.
Retry-After: <seconds>Server-supplied on 429 / some 5xxHonoured by SDK auto-retry.

8.2 Standard response headers​

Every response includes:

HeaderNotes
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-8Except 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:

  1. 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 against k9o_platform.slug_reservation per Slug addressing.
  2. X-K9o-Project header. When no @<projectSlug> marker is present, the gateway reads this header. Accepts either prefixed (proj_<base62>) or slug form.
  3. Token proj_id claim. 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):

  1. Service token presented. The token's bound project must match the resolved project context. Mismatch throws K9O_PROJECT_SCOPE_MISMATCH (HTTP 403).
  2. 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).
  3. Org-scoped operations. Accept user tokens without project context; an X-K9o-Project header 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.

PathMethod(s)Rationale
/@<projectSlug>/auth/jwks (on <orgSlug>.api.k9o.io)GETPublic per-project JWKS; consumers verify JWTs with this key without holding a token.
/auth/jwks (on <orgSlug>.api.k9o.io)GETOrg-scoped JWKS — same rationale; org tokens verified by customers' own services.
/extensions/jwks (on api.k9o.io root host)GETGateway hook-signing public key; extensions verify the gateway-signed JWT on inbound webhook deliveries.
/healthz (on api.k9o.io root host)GETPlatform 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.

StatusMeaningKError families
200OK; success with bodyn/a (success path)
201Created; success on resource creationn/a
202Accepted; asynchronous work in progressn/a
204No content; success on resource deletionn/a
400Validation, malformed request, anti-injection rejection at edgeK9O_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
401Auth missing or invalidK9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED
403Authorisation deniedK9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED, K9O_GATE_REQUIRED
404Resource not foundK9O_NOT_FOUND (resource-qualified per surface — e.g. K9O_SECRET_NOT_FOUND)
409State conflict; capacity cap; irreversible-gate conflictK9O_ALREADY_EXISTS, K9O_STATE_CONFLICT, K9O_IDEMPOTENCY_KEY_COLLISION, K9O_CUSTODY_MISMATCH, K9O_TIER_CAP_HIT, K9O_GATE_ALREADY_REDEEMED
422Semantically valid but operation rejectedK9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_CONSTRAINT_VIOLATION
429Capacity / rate limitK9O_RATE_LIMITED, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED
500Internal server errorK9O_INTERNAL_ERROR
502Upstream unavailableK9O_UPSTREAM_UNAVAILABLE
503Dependency unavailable; service temporarily downsurface-specific (e.g. K9O_BYOK_KEY_UNREACHABLE, K9O_HYOK_CLUSTER_UNREACHABLE, K9O_EXTENSION_DISABLED)
504Upstream timeoutsurface-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", ...}.

ElementFormat
IntegersUp 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.
TimestampsISO 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:

PackageSurface
@k9o/coreData + 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/kiboKibo vault operations — key custody, custody-mode descents, BYOK / HYOK lifecycle. Standalone, or composed via @k9o/core.
@k9o/gateGate (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):

LevelExamplesDiscipline
Top-level entry namespacesfrom, gate, kibo, functions, extensionsReserved for capability-level entry points. Catalogue closed; extends only via amendment.
Category sub-namespacesgate.passwordless.*, gate.identityProviders.*, kibo.byok.*Group related functions inside a capability. Per-capability catalogues declared in the chapter that owns the capability.
Marquee primitivesgate.signUp, gate.signIn, gate.whoamiFlat at the capability root for discoverability. Categorised operations sit below.
Function namescamelCase per §3.4Closed 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.