AtlasCms.Sdk 1.0.2

Atlas CMS .NET SDK

Simple .NET SDK for Atlas CMS with full async support and ASP.NET Core integration.

Compatibility

Core SDK (AtlasCms.Sdk)

• .NET: 10.0, 9.0, 8.0, 7.0
• C#: 11.0+

ASP.NET Core Extensions (AtlasCms.Sdk.AspnetCore)

• .NET: 10.0, 9.0, 8.0, 7.0
• C#: 11.0+

Features

• REST modules for Contents, Media Library, Users, Roles, Models, and Components
• GraphQL client helper
• Centralized HTTP client with consistent error handling
• Fluent query builders for query string DSL:
  • filter[{path}][{operator}]={value}
• Request-level API key override
• Fully typed APIs and test suite
• ASP.NET Core DI integration

Install

dotnet add package AtlasCms.Sdk

ASP.NET Core extensions (optional):

dotnet add package AtlasCms.Sdk.AspnetCore

Quick Start

using AtlasCms.Sdk;
using AtlasCms.Sdk.QueryBuilder;

var client = AtlasCmsClient.Create(new AtlasClientConfig
{
    ProjectId = "my-project-id",
    ApiKey = "YOUR_BEARER_TOKEN"
});

var query = new ContentsQueryBuilder()
    .Page(1)
    .Size(20)
    .Status(QueryStatus.Published)
    .Locale("en-US")
    .Filter("createdAt", "gte", "2026-01-01T00:00:00.000Z")
    .Sort("createdAt", SortDirection.Desc)
    .Build();

var result = await client.Contents.ListAsync("pages", query);

The SDK uses https://api.atlascms.io as the default base URL. Derived endpoints:

API Overview

AtlasCmsClient.Create(config)

public class AtlasClientConfig
{
    public required string ProjectId { get; init; }
    public required string ApiKey { get; init; }
    /// <summary>Defaults to "https://api.atlascms.io".</summary>
    public string? BaseUrl { get; init; }
    /// <summary>Optional custom HttpClient for testing or advanced scenarios.</summary>
    public HttpClient? HttpClient { get; init; }
}

Modules

client.Contents

client.Media

client.Users

client.Roles

client.Models

client.Components

client.Graphql

var response = await client.Graphql.ExecuteAsync<MyData>(
    new GraphqlRequest<Dictionary<string, object?>>
    {
        Query = "query GetPages { pages { id title } }"
    });

Query Builders

• ContentsQueryBuilder
• MediaQueryBuilder
• UsersQueryBuilder

All builders support:

Additional methods:

• ContentsQueryBuilder: .Status(QueryStatus.Published), .Locale("en-US"), .Resolve("media", "relations")
• MediaQueryBuilder: .Folder("images"), .SearchSubdirectory(true)
• UsersQueryBuilder: .Email("..."), .FirstName("..."), .IsActive(true), .Roles([...])

Per-request API key override

await client.Media.ListAsync(options: new AtlasRequestOptions
{
    ApiKey = "ANOTHER_BEARER_TOKEN"
});

Error handling

using AtlasCms.Sdk.Http;

try
{
    var content = await client.Contents.GetByIdAsync("pages", "id");
}
catch (AtlasHttpException ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    // Content not found — ex.StatusCode, ex.Message, ex.RequestId
}
catch (AtlasTimeoutException)
{
    // Request timed out
}
catch (AtlasNetworkException)
{
    // Network error
}

Custom base URL

Useful for local development or self-hosted instances:

var client = AtlasCmsClient.Create(new AtlasClientConfig
{
    ProjectId = "my-project-id",
    ApiKey = "YOUR_BEARER_TOKEN",
    BaseUrl = "https://my-custom-instance.example.com"
});

Custom HttpClient

Useful for testing or advanced scenarios (e.g. delegating handlers, mocks):

var client = AtlasCmsClient.Create(new AtlasClientConfig
{
    ProjectId = "my-project-id",
    ApiKey = "YOUR_BEARER_TOKEN",
    HttpClient = myCustomHttpClient
});

ASP.NET Core Integration

From configuration

Register in Program.cs:

builder.Services.AddAtlasCms(builder.Configuration);

In appsettings.json:

{
  "AtlasCms": {
    "ProjectId": "my-project-id",
    "ApiKey": "YOUR_BEARER_TOKEN",
    "BaseUrl": "https://api.atlascms.io"
  }
}

BaseUrl is optional and defaults to https://api.atlascms.io.

Using the fluent builder

builder.Services.AddAtlasCms(options => options
    .WithProjectId("my-project-id")
    .WithApiKey("YOUR_BEARER_TOKEN")
);

Direct configuration

builder.Services.AddAtlasCms(new AtlasClientConfig
{
    ProjectId = "my-project-id",
    ApiKey = "YOUR_BEARER_TOKEN"
});

Injection

public class PageController(AtlasCmsClient client)
{
    public async Task<IActionResult> GetPage(string id)
    {
        var page = await client.Contents.GetByIdAsync("pages", id);
        return Ok(page);
    }
}

Working with Dynamic Attributes

Content attributes are represented as JsonObject to support dynamic schemas:

// Read attributes
var title = content.Attributes?["title"]?.GetValue<string>();
var count = content.Attributes?["count"]?.GetValue<int>();

// Create with attributes
var created = await client.Contents.CreateAsync("pages", new CreateContentInput
{
    Locale = "en",
    Attributes = new JsonObject
    {
        ["title"] = "Page Title",
        ["featured"] = true
    }
});

Development

dotnet build
dotnet test