SearchStack.PublicApi 6.0.0

SearchStack.PublicApi

The official .NET client for the Search Stack public API (api.searchstack.dev) — search, ingest, and manage your indexes from any .NET app.

• Typed and HttpClient-based: a SearchStackClient with a service per area; types match the wire format (snake_case) one-to-one.
• Covers the full public surface: search and suggest, list/group management and versioning, ingestion, evals and judges, analytics, account details.
• The C# counterpart of @searchstack/public-api, mirroring its surface closely.

Targets & dependencies

• Multi-targets netstandard2.0 (.NET Framework 4.6.1+, Mono, Xamarin, Unity, .NET Core 2.0+) and net8.0.
• Only dependency is System.Text.Json, pulled in only on netstandard2.0 — in-box on net8.0, so zero transitive dependencies there.

Install

dotnet add package SearchStack.PublicApi

Quickstart

using SearchStack.PublicApi;

var client = new SearchStackClient("sk_live_...");

// Search version 1 of the "products" list in the "acme" account.
var result = await client.Search.SearchListAsync("acme", "products", 1,
    new SearchOptions { Query = "running shoes", Size = 10 });

if (result.IsSuccess)
{
    foreach (var hit in result.ToSuccess().Results)
        Console.WriteLine($"{hit.Name}: {hit.Text("colour")} — {hit.Number("price")}");
}
else
{
    // Methods never throw — errors come back as a typed Problem (see below).
    Console.Error.WriteLine($"{result.ToProblem().Status}: {result.ToProblem().Detail}");
}

Reading a result's fields

hit.Fields is a Dictionary<string, object?> of JsonElement values, because a field can hold text, a number, a date, or several of any of those. Read through the readers, not the dictionary:

hit.Text("colour")     // "red"             — one value, as itself
hit.Text("genre")      // "Comedy, Drama"   — several, joined
hit.Values("genre")    // ["Comedy", "Drama"]
hit.Number("price")    // 19.99

• A facet is always an array in a response — ["red"], [2006], [] when the record carries no value — whatever its cardinality. Searchable fields and resources stay scalar. The readers cover both.
• A field that is absent, null or empty reads as null (or an empty list) rather than throwing, and a name in the wrong case still finds its field.
• The same readers work on VerifiedOffer.Fields, where Number matters most — that one is the price you are about to charge.

Authentication

Configure one credential on construction; if both are supplied, the access token wins.

using SearchStack.PublicApi;

// API key -> sent as the `X-API-Key` header
var client = new SearchStackClient("sk_live_...");

// or, with full options:
var client = new SearchStackClient(new SearchStackClientOptions
{
    AccessToken = "eyJ...",                       // sent as Authorization: Bearer <token>
    BaseUrl = "https://api.searchstack.dev/",     // optional, defaults to production
});

Swap credentials at runtime (e.g. after refreshing a token):

client.SetAccessToken(newToken);
client.SetApiKey(newKey);

Bring your own HttpClient

By default the client creates and owns an HttpClient, disposed with the client. Pass your own — to control handlers, pooling or timeouts, or to use IHttpClientFactory — and it will not be disposed:

var client = new SearchStackClient(new SearchStackClientOptions
{
    ApiKey = "sk_live_...",
    HttpClient = httpClientFactory.CreateClient("searchstack"),
});

Result handling

No method throws on an HTTP error. Each resolves to a Response<T> (or Response for no-body calls) — either a success carrying the typed payload or a Problem (RFC 7807).

• Network and JSON errors surface as a Problem with Status 500.
• Cancellation still throws OperationCanceledException.
• result.Data and result.Problem are exposed directly for pattern-style checks.

var result = await client.Search.SearchListAsync("acme", "products", 1,
    new SearchOptions { Query = "boots" });

if (result.IsSuccess)
{
    SearchResponse page = result.ToSuccess();
    Console.WriteLine($"{page.TotalCount}, {page.Results.Count}");
}
else
{
    Problem problem = result.ToProblem();
    Console.Error.WriteLine($"{problem.Status}: {problem.Detail}");
}

Services

Search and suggest methods use the API's POST variants so options are passed as a typed object rather than a hand-built query string.

Examples

Text search a list version:

var res = await client.Search.SearchListAsync("acme", "products", 3, new SearchOptions
{
    Query = "running shoes",
    Size = 20,
    Filter = "brand eq 'Acme'",
    MinimumTextScore = 0.6,
});

Related results and a click-through:

var related = await client.Search.RelatedAsync("acme", "products", "sku-123",
    new RelatedOptions { Size = 5 });

if (related.IsSuccess)
{
    var page = related.ToSuccess();
    if (!string.IsNullOrEmpty(page.QueryId))
    {
        await client.Search.RecordListClickAsync("acme", "products", new RecordClickRequest
        {
            QueryId = page.QueryId!,
            ResultId = page.Results[0].Name,
        });
    }
}

Bulk insert. Each row carries its name under name — bulk insert reads that key and no other, so a row named title or search_result_name is dropped:

await client.SearchResults.BulkInsertWithFieldsAsync("acme", "products", new[]
{
    new Dictionary<string, object?> { ["name"] = "Trail Shoe", ["sku"] = "sku-1", ["price"] = 99 },
    new Dictionary<string, object?> { ["name"] = "Road Shoe", ["sku"] = "sku-2", ["price"] = 79 },
});

A group and its membership versions:

await client.Groups.AddListAsync("acme", "catalog",
    new AddListToGroupRequest { ListName = "products", Version = 4 });
await client.Groups.BumpVersionAsync("acme", "catalog");   // pin members to their latest
var versions = await client.Groups.GetVersionsAsync("acme", "catalog");

// search a specific, frozen membership version:
await client.Search.SearchGroupAsync("acme", "catalog",
    versions.ToSuccess().CurrentVersion, new SearchOptions { Query = "boots" });

// ...or follow the current members, whatever they are, on search, suggest and facet values:
await client.Search.SearchGroupLatestAsync("acme", "catalog", new SearchOptions { Query = "boots" });
await client.Suggest.GroupLatestAsync("acme", "catalog", "boo");
await client.Facets.GroupValuesLatestAsync("acme", "catalog", "colour");

A judge instruction (the prompt a judge grades against), then an eval set:

var verdict = await client.Judges.TryAsync("acme", "relevance-check", new TryJudgeRequest
{
    Context = new JudgeContextDto { Text = "waterproof hiking boots" },
    Candidate = new JudgeCandidateDto { Id = "sku-1", Text = "Trail Runner — mesh, not waterproof" },
});
if (verdict.IsSuccess) Console.WriteLine(verdict.ToSuccess().Passed);

var run = await client.Evals.RunAsync("acme", "relevance");   // async (202)
if (run.IsSuccess)
{
    var status = await client.Evals.GetRunStatusAsync("acme", "relevance", run.ToSuccess().RunId);
}

List analytics for a date range:

var report = await client.Analytics.GetListAsync("acme", "products", "2026-05-01", "2026-05-31");

Development

dotnet build
dotnet pack -c Release