Remote Config

Dynamic configuration values your app fetches at runtime, with stored segment and percentage conditions.

Remote config lets you change app behavior without shipping an update. Set key / value pairs on the server and the SDK fetches them with config.fetch(). Keys can also carry per-segment or percentage-rollout conditions, which apply to signed-in users; a caller without a session gets each key's default value.

How it works

Admins (or AI agents via MCP) set config values on the server. Every value has a type (string, number, boolean, json) and optional stored conditions for specific segments or a percentage of users.
The client SDK fetches the key → value map from GET /v1/client/config. The SDK keeps no cache of its own. The response carries Cache-Control: private, max-age=300, so in a browser a repeat config.fetch() within five minutes can return the browser's cached copy. Keep the result in app state and call fetch() again when you want fresh values.
The route returns an ETag header. A request that sends it back in If-None-Match gets 304 Not Modified while nothing changed, which helps when you call the route yourself. The SDK's fetch() sends no If-None-Match and always receives the full map.
Server-side version hashes make change detection fast: flipping a value bumps config_versions.version_hash, which changes the ETag.

SDK usage

Method signature:

client.config.fetch(): Promise<ConfigBundle> // { version, values }

Get a single value

const { values } = await client.config.fetch();
const dailyLimit = values['daily_limit'] as number | undefined;
// undefined if the key isn't set

Because each value is typed as unknown, cast to your expected type. Always provide a default:

const limit = ((await client.config.fetch()).values['daily_limit'] as number | undefined) ?? 10;

Get the full config map

const all = (await client.config.fetch()).values;
// { daily_limit: 10, feature_paywall_v2: true, ... }

Refresh

await client.config.fetch();
// Requests the map again (a browser can answer from its cache for up to 5 minutes)

Expo

import { Amba } from '@layers/amba-expo';
 
function SettingsScreen() {
  const [limit, setLimit] = useState<number | null>(null);
  const [paywall, setPaywall] = useState(false);
 
  useEffect(() => {
    (async () => {
      const { values } = await Amba.config.fetch();
      setLimit(typeof values['daily_limit'] === 'number' ? values['daily_limit'] : 10);
      setPaywall(values['feature_paywall_v2'] === true);
    })();
  }, []);
 
  return (
    <View>
      <Text>Daily limit: {limit}</Text>
      {paywall && <PaywallBanner />}
    </View>
  );
}

Amba.config.fetch() returns the full ConfigBundle ({ version, values }); read individual keys off values.

Manual refresh in Expo

await Amba.config.fetch();

Conditional values

A config key can carry conditions that target segments or a percentage of users. GET /v1/client/config evaluates them for a signed-in user, in order, and returns the value of the first condition that matches; a caller without a session gets the default value.

Example schema stored in remote_configs.conditions:

{
  "key": "feature_paywall_v2",
  "value_type": "boolean",
  "default_value": false,
  "conditions": [
    { "segment_id": "seg_power_users", "value": true },
    { "percentage": 25, "value": true }
  ]
}

This stores a default of false with a seg_power_users override and a 25% rollout condition; GET /v1/client/config returns false.

Setting config values

Via the Admin API

POST /v1/admin/projects/:projectId/config
Authorization: Bearer <developer token>
 
{
  "key": "daily_limit",
  "value": 10,
  "value_type": "number",
  "description": "Maximum daily actions allowed"
}

Via MCP

Agent: Add the new onboarding flag, off by default, with a stored 10% rollout condition.

amba_remote_configs_create({
  project_id: "proj_xxx",
  key: "feature_onboarding_v2",
  value: false,
  value_type: "boolean",
  description: "New onboarding experience",
  conditions: [{ percentage: 10, value: true }]
})

Via the CLI

amba config set daily_limit 10
amba config set feature_paywall_v2 true
amba config list

Routes reference

Method	Path	Description
`GET`	`/v1/client/config`	Fetch config values. Supports `If-None-Match` → 304.
`POST`	`/v1/admin/projects/:projectId/config`	Create or update a config value
`GET`	`/v1/admin/projects/:projectId/config`	List all active config values
`PATCH`	`/v1/admin/projects/:projectId/config/:key`	Update a specific config
`DELETE`	`/v1/admin/projects/:projectId/config/:key`	Delete a config value

MCP tools

Tool	Description
`amba_remote_configs_list`	List a project's config keys (values, types, conditions)
`amba_remote_configs_create`	Create / upsert a key with optional conditions
`amba_remote_configs_update`	Partially update a single key (only fields provided)
`amba_remote_configs_delete`	Remove a key

On this page