.NET SDK
The K9o.Core NuGet package is the .NET SDK for Kilimanjaro. It covers the full platform surface — data collections, Gate (IAK) authentication, schema migrations, platform functions, policies, audit log, org management, realtime subscriptions, and object storage — over a single, async-first client. Every I/O operation returns a Task; subscriptions expose IAsyncEnumerable<T>.
Runtime baseline: .NET 8 or later. The SDK targets net8.0 and is dependency-injection-ready out of the box.
Installation
dotnet add package K9o.Core
NuGet coordinate: K9o.Core
Setup
Construct a single K9oClient per application lifetime. The client takes org slug, project slug, and an API key. BaseUrl is optional — it defaults to https://api.k9o.io; if you pass the bare apex alongside OrgSlug, the SDK derives the canonical https://<orgSlug>.api.k9o.io subdomain for you. Pass it explicitly (as shown below) for clarity, or omit it entirely. Read the API key from an environment variable — never hard-code a secret in source.
using K9o;
var k9o = K9oClient.Create(new K9oOptions {
BaseUrl = "https://acme.api.k9o.io", // optional
ApiKey = Environment.GetEnvironmentVariable("K9O_API_KEY"),
OrgSlug = "acme",
ProjectSlug = "member-portal",
});Showing example in .NET
Self-hosted and Sovereign deployments
Customers running on their own infrastructure pass their own host as BaseUrl instead of the Kilimanjaro Cloud subdomain. BaseUrl is scheme and host only — supplying a path-bearing value (for example, https://api.k9o.io/v2) throws KError with code K9O_INVALID_BASE_URL at construction time.
using K9o;
var k9o = K9oClient.Create(new K9oOptions {
BaseUrl = "https://platform.acme.internal", // scheme + host only; no path
OrgSlug = "acme",
ProjectSlug = "member-portal",
ApiKey = Environment.GetEnvironmentVariable("K9O_API_KEY"),
});Showing example in .NET
Valid override examples: https://platform.acme.internal, http://localhost:8080. See the API conventions for the full URL grammar.
Dependency injection
K9oClient registers cleanly as a singleton in IServiceCollection:
// Program.cs
builder.Services.AddSingleton(K9oClient.Create(new K9oOptions {
BaseUrl = builder.Configuration["K9o:BaseUrl"], // optional
OrgSlug = builder.Configuration["K9o:OrgSlug"]!,
ProjectSlug = builder.Configuration["K9o:ProjectSlug"]!,
ApiKey = builder.Configuration["K9o:ApiKey"],
}));Showing example in .NET
You can bind K9oOptions from appsettings.json. Refer to the full API reference for the options shape.
Getting started
The first operation most applications make is querying a data collection — build a query, await it, read Data and Meta, and handle KError in a catch block. Signing users in has its own section below.
using K9o;
var k9o = K9oClient.Create(new K9oOptions {
BaseUrl = "https://acme.api.k9o.io", // optional
ApiKey = Environment.GetEnvironmentVariable("K9O_API_KEY"),
OrgSlug = "acme",
ProjectSlug = "member-portal",
});
try
{
var resp = await k9o.From("posts").Select().Limit(10).ExecuteAsync<Post>();
foreach (var row in resp.Data)
Console.WriteLine(row);
Console.WriteLine($"next cursor: {resp.Meta.Cursor?.Next}");
}
catch (KError e)
{
Console.Error.WriteLine($"[{e.Code}] {e.Message}: {e.Recommendation}");
}Post { Id = post_1, Title = Hello }
next cursor:Showing example in .NET
Method naming. Async methods carry the Async suffix per .NET convention (ExecuteAsync, SignInAsync, and so on). Response properties are PascalCase (response.Data, response.Meta.Cursor?.Next). Wire JSON is camelCase; the SDK maps it via [JsonPropertyName] attributes — you interact only with the PascalCase surface.
Row types. ExecuteAsync<T> deserializes each row into the type you give it. The wire format is camelCase, so a row type needs [JsonPropertyName] attributes:
public class Customer
{
[JsonPropertyName("id")] public string Id { get; set; } = "";
[JsonPropertyName("email")] public string Email { get; set; } = "";
}
Meta.Timing carries TotalMs (the whole request), and Meta.Cursor is null on the last page.
Authenticating your End-Users
This SDK covers password sign-in and session management: SignUpAsync, SignInAsync, SignOutAsync, WhoAmIAsync, and RefreshTokenAsync. Social-IdP and passwordless flows (magic-link, OTP) are browser and mobile flows — see the TypeScript SDK and mobile SDK pages, or the Auth API reference for those and the full Gate surface. RevokeAllSessionsAsync ends every session of the signed-in user, this device included; access tokens already issued live until they expire. See Session lifetime and sign-out.
var result = await k9o.Gate.SignInAsync(new SignInInput { Email = "[email protected]", Password = "…" });
Console.WriteLine($"signed in: {result.Data.GetProperty("user").GetProperty("id").GetString()}");
Console.WriteLine($"access token: {result.Data.GetProperty("session").GetProperty("accessToken").GetString()}");signed in: eu_8f3kQ2mZ
access token: eyJhbGciOiJSUzI1NiIs...Showing example in Password
Handling errors
Every platform error surfaces as a KError exception (KError : Exception). Catch it, switch on Code, and fall through to a generic handler for codes you do not recognise. Code always carries the full K9O_-prefixed wire code.
try
{
var response = await k9o.From("posts").Select().Limit(10).ExecuteAsync<Post>();
// … use response.Data
}
catch (KError e)
{
switch (e.Code)
{
case "K9O_TIER_CAP_HIT":
// Tier cap reached; e.Recommendation is a string, or null
Console.Error.WriteLine($"Tier cap: {e.Recommendation}");
break;
case "K9O_UNAUTHENTICATED":
// Token missing or expired; prompt the user to sign in again
Console.Error.WriteLine("Session expired — please sign in again.");
break;
case "K9O_INVALID_BASE_URL":
// SDK-local error, raised before any request: BaseUrl was path-bearing; fix the options
Console.Error.WriteLine($"Bad base URL: {e.Message}");
break;
default:
// Unknown code — log and rethrow
Console.Error.WriteLine($"[{e.Code}] {e.Message}");
throw;
}
}Showing example in .NET
KError properties:
| Property | Type | Description |
|---|---|---|
Code | string | SCREAMING_SNAKE_CASE error code from the error catalogue |
Message | string | Human-readable description; safe to log and display |
Context | object | Structured fields specific to this error family |
Recommendation | string? | Optional remediation hint |
Error codes are drawn from the platform's closed taxonomy. See the error catalogue for the full list and per-code Context shapes.
Async and streaming
Every I/O method on K9oClient is async and returns a Task. For realtime subscriptions — receiving collection inserts, updates, and deletes as they happen — the SDK delivers events via IAsyncEnumerable<T>, the idiomatic .NET async-stream pattern:
// Subscribe to changes on the "orders" collection
await foreach (var evt in k9o.Realtime.SubscribeAsync(Realtime.Topic.Collection("orders")))
Console.WriteLine($"{evt.EventType}: {evt.Payload}"); // RealtimeEvent: Topic, EventType, Payload, OccurredAtrow_inserted: {"id":"order-124","total":42}
row_deleted: {"id":"order-124"}Showing example in .NET
The transport is Server-Sent Events: a stream lasts up to 300 seconds; to continue after it ends, reconnect with the last event id as Last-Event-ID and drop duplicates by eventId (the client contract, see the Realtime API reference). There is no initial-state replay; read the current rows first, then subscribe for changes.
Streams
Streams are ordered and replayable. maxBytes is at least 10485760 (10 MiB), and the stream's Slug is what the other calls take. SubscribeAsync takes the start sequence as text and Sequence arrives as a string. Leave a subscription with break: the cancellation token is only checked when the next frame arrives, so on a quiet stream cancelling does not end the loop at once.
var orders = (await k9o.Streams.CreateAsync("orders", 10_485_760)).Data!;
await k9o.Streams.PublishAsync(orders.Slug, new { id = 1, total = 42 }, "eu.new");
await k9o.Streams.PublishAsync(orders.Slug, new { id = 2, total = 17 });
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
await foreach (var e in k9o.Streams.SubscribeAsync(orders.Slug, "0", cts.Token))
{
Console.WriteLine($"{e.Sequence} {JsonSerializer.Serialize(e.Data)}"); // 1 {"id":1,"total":42}
if (e.Sequence == "2") break;
}
var page = (await k9o.Streams.ReplayAsync(orders.Slug, fromSequence: 0, limit: 10)).Data!;
Console.WriteLine($"{page.Events.Count} {page.HasMore}");1 {"id":1,"total":42}
2 {"id":2,"total":17}
2 FalseShowing example in .NET
See also
- API reference — full platform surface, request/response shapes, all endpoints
- Conventions — response envelope, KError shape, URL grammar, pagination
- CLI —
k9ocommand-line tool for migrations, function deploy, and project management - SDKs — TypeScript, Python, Go, Rust, Java, Kotlin, Swift, and more