Quickstart

Your first authenticated call against the Ekso API. Five minutes from new project to listing items.

What you’ll build

A console app that authenticates with an API key against your Ekso install, lists the first page of items, and prints their keys. Five minutes start to finish.

1. New project

mkdir ekso-sample && cd ekso-sample
dotnet new console
dotnet add package Ekso.Sdk

2. Provision an API key

If you don’t already have one, mint one via the CLI:

ekso api-key create --name "sdk-sample" --url https://ekso.acme.com

The response includes a rawKey field — capture the value (ek_live_...) once. The backend never returns it again. Set it on your shell:

export EKSO_API_KEY=ek_live_xxx
export EKSO_URL=https://ekso.acme.com

3. Write the program

Replace Program.cs:

using Ekso.Sdk;
using Ekso.Sdk.Authentication;
using Ekso.Sdk.Exceptions;
using Ekso.Sdk.Generated.Models;

var url = Environment.GetEnvironmentVariable("EKSO_URL")
    ?? throw new InvalidOperationException("Set EKSO_URL first.");
var apiKey = Environment.GetEnvironmentVariable("EKSO_API_KEY")
    ?? throw new InvalidOperationException("Set EKSO_API_KEY first.");

var client = new EksoClient(new EksoClientOptions
{
    BaseUrl = url,
    Auth = new ApiKeyAuth(apiKey),
});

try
{
    // First call — list the field collection. Cheap, validates auth + connectivity.
    var fields = await client.Api.Field.GetAsync();
    var coreCount = (fields?.TypeText?.Count ?? 0)
                  + (fields?.TypeList?.Count ?? 0)
                  + (fields?.TypePicker?.Count ?? 0);
    Console.WriteLine($"Connected to '{url}'. {coreCount} fields configured.");

    // Now list a first page of items
    var page = await client.Api.Item.List.PostAsync(new ItemListRequest());
    Console.WriteLine($"\nFirst {page?.Data?.Count ?? 0} items:");
    foreach (var item in page?.Data ?? [])
    {
        Console.WriteLine($"  {item.Key}: {item.Name}");
    }
}
catch (EksoAuthException ex)
{
    Console.Error.WriteLine($"Auth failed ({ex.Reason}): {ex.Message}");
    Environment.Exit(3);
}
catch (EksoApiException ex)
{
    Console.Error.WriteLine($"API error {ex.StatusCode}: {ex.Message}");
    Environment.Exit(1);
}

4. Run

dotnet run

Expected output:

Connected to 'https://ekso.acme.com'. 14 fields configured.

First 25 items:
  PRD-1: Set up CI/CD pipeline
  PRD-2: Database migration plan
  HELP-1: Customer escalation: missing invoice
  ...

What just happened

• EksoClient was constructed against your install URL with bearer-token auth.
• client.Api.Field.GetAsync() issued a GET /api/field and deserialized the response into a typed FieldCollection.
• client.Api.Item.List.PostAsync(...) issued a POST /api/item/list with an ItemListRequest body and deserialized into a typed ItemListResponse.
• The EksoAuthException and EksoApiException catches surface specific failure shapes — see Error handling for the full hierarchy.

Next ideas

Now that you have a working client, try:

// Create a custom field
var field = new DataFieldText
{
    Name = "Customer Reference",
    Description = "Internal reference id",
    ContentType = "ContentText",
    Maximum = 64,
};
await client.Api.Field.Text.PostAsync(field);

// Create an item
var item = new DataItem
{
    Name = "Onboard new customer",
    ProcessId = /* an id from your install */ "...",
    ContainerId = /* an id from your install */ "...",
};
var created = await client.Api.Item.PostAsync(item);
Console.WriteLine($"Created {created!.Key}");

The full surface — every typed method on client.Api.* — maps 1-to-1 to the operations in the API Reference. Auto-completion in your IDE is the fastest discovery path.

Production hardening

• Don’t hard-code keys. Read from a secrets manager, not from environment variables on a developer’s laptop.
• Catch the right exceptions. EksoRateLimitException.RetryAfter tells you exactly how long to back off; EksoNetworkException is the only one you should reflexively retry without thought.
• Set a sensible HTTP timeout. The SDK uses Kiota’s default — wrap calls in CancellationToken if you need tighter bounds.
• Use RefreshableBearerAuth if you’re acting on behalf of a user — token rotation is the right model. ApiKeyAuth is for service identities.

Next steps

• Authentication — ApiKeyAuth vs RefreshableBearerAuth.
• Error handling — exception hierarchy + retry strategies.
• CLI/SDK marker — operations that are gated for SDK callers.