Guides

.NET quickstart

Install the .NET SDK, insert a document, search it, and handle API errors with async C#.

The NuGet package is named AetherDb.Sdk, but the namespace you import in code is Aether.Sdk.

1. Install the SDK

Bash
dotnet new console -n AetherQuickstart
cd AetherQuickstart
dotnet add package AetherDb.Sdk

Set your API key:

Bash
export AETHER_API_KEY="your-api-key"

The SDK targets .NET 8.0 and .NET Standard 2.0. All network operations are async and return Task or Task<T>.

Replace Program.cs with this complete example:

C#
using Aether.Sdk;

using var client = new AetherClient(new AetherClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("AETHER_API_KEY"),
});

var doc = await client.InsertTextAsync(
    "Employees accrue 20 days of PTO per year.",
    "pto-policy.txt");

Console.WriteLine($"Inserted {doc.DocId}");

var results = await client.SearchAsync("vacation days", k: 3);
foreach (var hit in results)
{
    Console.WriteLine($"{hit.DocId} {hit.Score} {hit.Title}");
}

Run it:

Bash
dotnet run

Expected output:

text
Inserted doc_...
doc_... 87 pto-policy.txt

Search hits carry Score, a 0-100 relevance value where higher is better. Use RetrieveAsync when you want the matching document text in the same call:

C#
var passages = await client.RetrieveAsync("How much PTO do employees get?", k: 3);
foreach (var passage in passages)
{
    Console.WriteLine(passage.Content);
}

3. Handle errors

Catch AetherApiException for HTTP responses from Aether and inspect StatusCode, ErrorCode, and IsRetryable.

C#
using System.Net;
using Aether.Sdk;

try
{
    await client.InsertTextAsync("Important note", "note.txt");
}
catch (AetherApiException ex) when (ex.StatusCode == HttpStatusCode.TooManyRequests)
{
    Console.WriteLine("Rate limited. Back off and retry after the retry-after header window.");
}
catch (AetherApiException ex) when (ex.ErrorCode == "free_limit_exceeded")
{
    Console.WriteLine("Plan limit reached. Upgrade before retrying this insert.");
}
catch (AetherApiException ex) when (ex.IsRetryable)
{
    Console.WriteLine($"Transient Aether error: {ex.StatusCode}");
}

4. Next steps