smartSettings API Reference

Base URLs

Environment	Base URL
Sandbox	https://api.dev.smartobjx.com/settings-demo
Production	Provided by your smartObjx account administrator

All endpoints require authentication headers.

Domain Model

Application

Entry point for a body of settings. Applications may have multiple Configurations. Has Name, Description, ConfigId, and Start date. Think of it as a settings container for a software application or module.

Configuration

A collection of Settings. May also contain nested Configurations. No limit on depth — helps break complex settings into manageable, hierarchical pieces (e.g., Application → Module → Feature).

Setting

An individual setting with Name, Description, type, value, optional encryption, initialization vector, and a start date for version activation. Settings support scheduled activation — set a future start date and the value takes effect automatically.

Distribution

Shows what percentage of clients use the default setting vs. have their own custom override value. Useful for understanding how customized your tenant base is for a given setting.

---

Endpoints

GET /application

List all Applications. Returns a JSON array of Application objects.

Response

[
  {
    "$id": "1",
    "Name": "My SaaS App",
    "Description": "Main application settings",
    "ConfigId": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "OID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "SubscriberID": "33f13e11-c505-48fa-9e6b-85f0b1c4599c",
    "OwnerID": "45ef2936-160e-47dc-bd17-3dc0060acec9",
    "Version": "2024-01-01T00:00:00Z"
  }
]

cURL example

curl -X GET "https://api.dev.smartobjx.com/settings-demo/application" \
  -H "Ocp-Apim-Subscription-Key: fd8efd80-f215-4c73-95f2-23841e98acbd" \
  -H "Ocp-Apim-POV-Key: 45ef2936-160e-47dc-bd17-3dc0060acec9"

---

POST /application

Create or save an Application.

Request body

{
  "Name": "My SaaS App",
  "Description": "Configuration for the main application"
}

Response

Returns the created/updated Application object with generated OID and ConfigId.

---

GET /configuration/{configId}

Get a Configuration by its ConfigId. Returns the Configuration with all its Settings and nested Configurations.

Parameters

Parameter	Type	Description
configId	path (GUID)	The ConfigId of the configuration to retrieve

Response

Returns a Configuration object containing its Settings array and any nested Configurations.

---

POST /configuration/{appId}

Save a Configuration within an Application.

Parameters

Parameter	Type	Description
appId	path (GUID)	The OID of the parent Application

Request body

A Configuration object with its Settings.

---

GET /distribution/{oid}/{settingName}

Get the distribution of a setting across clients. Shows how many clients use the default value vs. have custom overrides.

Parameters

Parameter	Type	Description
oid	path (GUID)	The OID of the configuration or application
settingName	path (string)	The name of the setting to check

Response

Returns a list of SettingDistribution objects showing the value breakdown across clients.

---

Use Cases

• Per-customer feature toggles in multi-tenant SaaS
• Encrypted sensitive configuration values
• Versioned settings with scheduled activation dates
• Setting distribution analytics across client base
• White-label configuration for reseller partners
• Nested configuration hierarchies for complex applications

Integration Code

JavaScript

const headers = {
  'Content-Type': 'application/json',
  'Ocp-Apim-Subscription-Key': 'your-subscription-key',
  'Ocp-Apim-POV-Key': 'your-pov-key'
};

// List all Applications
const apps = await fetch('https://your-settings-api/application', {
  method: 'GET', headers
}).then(r => r.json());
// Returns: [{Name, ConfigId, OID, Version, ...}, ...]

// Get a Configuration by ConfigId
const config = await fetch(`https://your-settings-api/configuration/${configId}`, {
  method: 'GET', headers
}).then(r => r.json());

// Check setting distribution across clients
const dist = await fetch(
  `https://your-settings-api/distribution/${oid}/${settingName}`, {
  method: 'GET', headers
}).then(r => r.json());

C# with smartConnectors

// NuGet: Install SmartObjx.Connectors
var config = new smartConnectorInstace();
config.BasePath = "https://your-settings-api-url";
config.ApiKey.Add("Ocp-Apim-POV-Key", "your-pov-key");
config.ApiKey.Add("Ocp-Apim-Subscription-Key", "your-subscription-key");

// List all applications
ApplicationApi appApi = new ApplicationApi(config);
// GET /application returns all applications

// Create an application
Application application = new Objx.Settings.Application("My App");
application = appApi.SaveApplication(null, application);

// Get a configuration
SettingsApi settingsApi = new SettingsApi(config);
Configuration configuration = settingsApi.FindConfigurationWith(
    new Guid("your-config-id"));
string json = configuration.ConfigtoJson();

// Add a setting to a configuration
configuration.AddSetting(setting);
settingsApi.SaveConfiguration(applicationId, null, configuration);

// Find a configuration by name
Configuration namedConfig = settingsApi.FindConfigNamed("MyConfigName");

// Check setting distribution across clients
List<SettingDistribution> dist = settingsApi.GetDistributionList(oid, settingName);

Browser IDE

smartSettings includes a browser-based IDE for managing settings visually. Try the sandbox IDE at settings-demo.smartobjx.com.

Related

• Authentication — required headers for all API calls
• smartConnectors SDK — NuGet and npm packages
• smartSettings product page