ClariveSDK 0.3.0

ClariveSDK for .NET

The official C# SDK for the Clarive Public API. Retrieve prompt entries, render templates with variable substitution, and integrate it all into your .NET apps with a single AddClarive() call.

Targets .NET 9+. No dependencies beyond Microsoft.Extensions.Http and Microsoft.Extensions.Http.Resilience.

Install

dotnet add package ClariveSDK

Quick start

using ClariveSDK;
using ClariveSDK.Models;

var options = new ClariveOptions
{
    ApiKey = "cl_your_api_key",
    BaseUrl = "https://app.clarive.com"
};

using var httpClient = new HttpClient();
var client = new ClariveClient(httpClient, options);

// Fetch a published prompt entry
var entry = await client.GetEntryAsync(entryId);

// Render it with template variables
var response = await client.GenerateAsync(entryId, new GenerateRequest
{
    Fields = new Dictionary<string, string>
    {
        ["companyName"] = "Acme Corp",
        ["customerMessage"] = "I need help with my order"
    }
});

foreach (var prompt in response.RenderedPrompts)
    Console.WriteLine(prompt.Content);

Dependency injection

For ASP.NET Core or any host that uses Microsoft.Extensions.DependencyInjection, register the SDK in one line:

builder.Services.AddClarive(opts =>
{
    opts.ApiKey = builder.Configuration["Clarive:ApiKey"]!;
    opts.BaseUrl = "https://app.clarive.com";
});

Or bind directly from configuration:

builder.Services.AddClarive(builder.Configuration.GetSection("Clarive"));

{
  "Clarive": {
    "ApiKey": "cl_your_api_key",
    "BaseUrl": "https://app.clarive.com"
  }
}

Then inject IClariveClient wherever you need it:

public class PromptService(IClariveClient clarive)
{
    public async Task<string> RenderAsync(Guid entryId, Dictionary<string, string> fields)
    {
        var result = await clarive.GenerateAsync(entryId, new GenerateRequest { Fields = fields });
        return result.RenderedPrompts.First().Content;
    }
}

The DI registration uses IHttpClientFactory under the hood, so you get proper HttpClient lifecycle management for free.

Resilience

Built-in retry, circuit breaker, and timeout are enabled by default when using AddClarive(). The defaults:

Override them:

builder.Services.AddClarive(opts =>
{
    opts.ApiKey = "cl_your_api_key";
    opts.Resilience.MaxRetries = 5;
    opts.Resilience.Timeout = TimeSpan.FromSeconds(60);
});

Or disable the built-in pipeline entirely and bring your own Polly policies:

builder.Services.AddClarive(opts =>
{
    opts.ApiKey = "cl_your_api_key";
    opts.Resilience.Enabled = false;
});

Error handling

API errors throw typed exceptions, all extending ClariveApiException:

ClariveValidationException carries a Details dictionary mapping field names to error messages, so you can tell the user exactly what went wrong.

try
{
    var result = await client.GenerateAsync(entryId, request);
}
catch (ClariveValidationException ex)
{
    foreach (var (field, error) in ex.Details)
        Console.WriteLine($"{field}: {error}");
}
catch (ClariveRateLimitException)
{
    // Back off and retry
}
catch (ClariveApiException ex)
{
    Console.WriteLine($"API error {ex.ErrorCode}: {ex.Message}");
}

API reference

IClariveClient

Models

PromptEntry — a published prompt entry containing one or more prompts.

• Id (Guid), Title (string), Version (int), SystemMessage (string?), Prompts (list of Prompt), Tags (list of string), UpdatedAt (DateTime), PublishedAt (DateTime?), Tabs (list of TabSummary), TabCount (int)

Prompt — a single prompt within an entry.

• Content (string), Order (int), IsTemplate (bool), TemplateFields (list of TemplateField?)

TemplateField — defines a {{variable}} placeholder in a template prompt.

• Id (Guid), PromptId (Guid), Name, Type (string/int/float/enum), EnumValues, DefaultValue, Min, Max

GenerateRequest — the request body for GenerateAsync.

• Fields (Dictionary<string, string>?) — keys are field names, values are the substitutions

GenerateResponse — rendered output from GenerateAsync.

• Id, Title, Version, SystemMessage, RenderedPrompts (list of RenderedPrompt)

RenderedPrompt — a prompt with all template variables replaced.

• Content (string), Order (int)

EntrySummary — compact entry representation from ListEntriesAsync.

• Id, Title, Version, HasSystemMessage, IsTemplate, IsChain, PromptCount, FirstPromptPreview, Tags, CreatedAt, UpdatedAt, Tabs (list of TabSummary), TabCount (int)

TabSummary — summary of a tab on a prompt entry.

• Id (Guid), Name (string), IsMainTab (bool), ForkedFromVersion (int?)

PaginatedResponse<T> — pagination wrapper.

• Items (list of T), TotalCount (int), Page (int), PageSize (int)

TagInfo — a tag with its entry count.

• Name (string), EntryCount (int)

ListEntriesOptions — query parameters for ListEntriesAsync.

• FolderId, Tags, TagMode, Page, PageSize, Search, SortBy (all optional)

Configuration

ClariveOptions controls SDK behavior:

HTTPS is enforced by default. If you're developing against a local instance on http://localhost, set AllowInsecureHttp = true.

Build and test

cd sdks/csharp
dotnet build
dotnet test
dotnet run --project example/ClariveSDK.Example

License

See the repository root for license information.