Amba

Remote Config

Set, read, update, and delete remote-config keys with segment-based + percentage rollout overrides.

Remote config is a per-project key-value store with typed values, segment-based overrides, and percentage rollouts. Client SDKs fetch the evaluated bundle from GET /client/config; every write here recomputes the ETag-backing hash so clients pick changes up on their next poll.

Endpoints

MethodPathDescription
POST/admin/projects/:projectId/configUpsert a key.
GET/admin/projects/:projectId/configList every key with is_active.
PATCH/admin/projects/:projectId/config/:keyPartial update, incl. kill switch.
DELETE/admin/projects/:projectId/config/:keyDelete a key.
GET/admin/projects/:projectId/config/historyChange history for the project.
GET/admin/projects/:projectId/config/:key/historyChange history for one key.

Every write records a change history entry in the same transaction; the two history routes below read it.

POST /admin/projects/:projectId/config

Upsert by key. Accepts the SetConfigInput shape from @layers/amba-shared.

Request

FieldTypeRequiredDescription
keystringyesUnique key name.
valueanyyesJSON-serializable value.
value_type"string" | "number" | "boolean" | "json"noDefaults to "string".
descriptionstringnoFree-form developer notes.
conditionsConfigCondition[]noSegment + percentage overrides.

ConfigCondition shape

{ "segment_id": "…", "percentage": 50, "value": "override-value" }

Evaluated in order — first matching condition wins; otherwise default_value is used.

Upserting a key that is switched off keeps it off; turn it back on with PATCH and is_active: true.

Response 201

{
  "data": {
    "id": "…",
    "key": "…",
    "value": "…",
    "value_type": "string",
    "description": null,
    "conditions": [],
    "default_value": "…",
    "is_active": true,
    "version": 1,
    "created_at": "…",
    "updated_at": "…"
  }
}

Errors

  • 500 SET_FAILED.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/config
developer auth
curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "welcome_message",
  "value": "Hello!",
  "value_type": "string"
}'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/config" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"key":"welcome_message","value":"Hello!","value_type":"string"}'

GET /admin/projects/:projectId/config

List every config row ordered by key, switched on or off. Apps are served only the rows with is_active: true. ?include_system=true adds the platform-provided keys.

Response 200

{
  "data": [
    {
      "key": "…",
      "value": "…",
      "value_type": "string",
      "conditions": [],
      "is_active": true,
      "version": 1
    }
  ]
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/config
developer auth
curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/config" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

PATCH /admin/projects/:projectId/config/:key

Partial update. Only keys present in the body are changed. If value is present, version is incremented. Any successful mutation recomputes the singleton config-version hash under a transactional lock so the ETag stays consistent.

is_active is the kill switch. false stops serving the key: GET /v1/client/config leaves it out, so the SDK returns the app's cached or shipped default, and its value, conditions and history are kept. true serves it again.

Request

FieldType
valueany
descriptionstring | null
conditionsConfigCondition[]
is_activeboolean

Response 200

Updated row.

Errors

  • 400 INVALID_INPUT — is_active is not a boolean.
  • 404 NOT_FOUND.
  • 500 UPDATE_FAILED.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D
developer auth
curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D' \
  -H 'Content-Type: application/json' \
  -d '{
  "value": "Welcome back!"
}'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH "${BASE_URL}/admin/projects/${PROJECT_ID}/config/{key}" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"value":"Welcome back!"}'

DELETE /admin/projects/:projectId/config/:key

Hard-delete the row. Recomputes the ETag hash. The key's history is kept.

Response 200

{ "data": { "deleted": true } }

Errors

  • 500 DELETE_FAILED.

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D
developer auth
curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/config/{key}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

GET /admin/projects/:projectId/config/history

Every remote config change in the project, newest first. Each write (create, update, delete, and the kill switch) records one entry in the same transaction as the write; a write that changes nothing records none.

Query

ParamTypeDescription
limitinteger1-200, default 50.
beforestringThe id of the last entry from the previous page, for older ones.

Response 200

{
  "data": [
    {
      "id": "…",
      "config_key": "feature_paywall_v2",
      "action": "deactivate",
      "actor_kind": "pat",
      "actor_id": "…",
      "before": {
        "value": true,
        "default_value": true,
        "value_type": "boolean",
        "description": null,
        "conditions": [],
        "is_active": true,
        "is_system": false,
        "version": 3
      },
      "after": {
        "value": true,
        "default_value": true,
        "value_type": "boolean",
        "description": null,
        "conditions": [],
        "is_active": false,
        "is_system": false,
        "version": 3
      },
      "created_at": "…"
    }
  ]
}

action is create, update, delete, activate or deactivate (a write that switched is_active). actor_kind is pat (a developer; actor_id is the developer id), server_key (actor_id is the key id, or internal_token for your deployed functions), operator (a delegated operator token id) or system (a scheduled content delivery, actor_id content_delivery). A create has no before and a delete has no after.

Errors

  • 400 INVALID_INPUT — limit outside 1-200, or before is not a change id.
  • 500 HISTORY_FAILED.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/config/history
developer auth
curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config/history'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/config/history?limit=20" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

GET /admin/projects/:projectId/config/:key/history

The changes to one key, newest first, in the same shape and with the same limit / before paging. A deleted key keeps its history; a key never written answers an empty list.

Response 200

{
  "data": [
    {
      "id": "…",
      "config_key": "…",
      "action": "update",
      "actor_kind": "pat",
      "actor_id": "…",
      "before": {},
      "after": {},
      "created_at": "…"
    }
  ]
}

Errors

  • 400 INVALID_INPUT.
  • 500 HISTORY_FAILED.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D/history
developer auth
curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/config/%7B%7Bkey%7D%7D/history'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/config/{key}/history" \
  -H "Authorization: Bearer ${DEV_TOKEN}"