> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Configurations

> Server-driven configuration payloads delivered to the SDK

A **Remote Configuration** is a named payload that the Qonversion SDK fetches at runtime. Use it to feature-flag experiments, change onboarding copy, tune paywall defaults, or deliver any server-controlled JSON to your app without a new release. Configurations can be narrowed with targeting rules, attached to experiment groups, or pinned to specific users.

## Key concepts

* **Config ID** — Stable identifier (UUID) for the configuration, used in the API path.
* **Context key** — Optional key the SDK uses to look up this configuration.
* **Status** — `draft`, `active`, or `archived`. Only `active` configurations are served to the SDK. Archiving is terminal; an archived configuration can only be deleted. Change it via `PATCH /remote-configurations/{config_id}/status`.
* **Payload values** — The actual JSON object delivered to the SDK, e.g. `{"button_color": "#FF0000"}`. Read and replaced through the dedicated `payload` endpoint, and also returned read-only inline on a single-configuration GET.
* **Payload mapping** — The key → type *schema* that tells the SDK how to interpret each payload key, e.g. `{"button_color": "Color"}`. Types are `String`, `Number`, `Bool`, `Json`, `Color`, `Products`, `Screens`. Managed through the `payload-mapping` endpoint. The mapping describes the shape of the payload; it is **not** the values themselves.
* **Targeting** — `segment_percent` (0–100) rolls the configuration out to a fraction of the audience, and `segmentation_conditions` narrows it with attribute rules. Both are set on create/update and returned on read. The rollout is deterministic per user: raising the percent only adds users, lowering it only removes users from the top buckets on their next request. Automatic assignments are re-evaluated after targeting edits (rolling out project by project); manual pins are never re-evaluated. See [How targeting and assignment works](/docs/remote-config-targeting).
* **User attachment** — `POST /remote-configurations/{config_id}/users/{user_id}` pins a specific user to this configuration, overriding targeting rules; the pin is never re-evaluated and survives config edits until `DELETE`, archive, or delete. Both attach and detach invalidate the SDK's in-memory config cache.
* **Experiments** — Remote configurations can be delivered as an experiment group payload.

<Note>
  **Payload values vs. payload mapping** are two sibling concepts. The **values** (`payload`) are the JSON delivered to the SDK; the **mapping** (`payload-mapping`) is the key → type schema describing how to read that JSON. They are edited through separate endpoints.
</Note>

## Available endpoints

| Method | Endpoint                                             | Description                                        | Status |
| ------ | ---------------------------------------------------- | -------------------------------------------------- | ------ |
| GET    | `/remote-configurations`                             | List remote configurations                         | New    |
| POST   | `/remote-configurations`                             | Create a remote configuration                      | New    |
| GET    | `/remote-configurations/{config_id}`                 | Get a remote configuration (with inline `payload`) | New    |
| PUT    | `/remote-configurations/{config_id}`                 | Replace a remote configuration                     | New    |
| DELETE | `/remote-configurations/{config_id}`                 | Delete a remote configuration                      | New    |
| PATCH  | `/remote-configurations/{config_id}/status`          | Change status (`draft`, `active`, `archived`)      | New    |
| GET    | `/remote-configurations/{config_id}/payload`         | Get the payload values                             | New    |
| PUT    | `/remote-configurations/{config_id}/payload`         | Replace the payload values                         | New    |
| GET    | `/remote-configurations/{config_id}/payload-mapping` | Get the payload mapping                            | New    |
| POST   | `/remote-configurations/{config_id}/payload-mapping` | Set the payload mapping                            | New    |
| POST   | `/remote-configurations/{config_id}/users/{user_id}` | Attach a user to this configuration                | New    |
| DELETE | `/remote-configurations/{config_id}/users/{user_id}` | Detach a user                                      | New    |

`POST` and `PUT` on a configuration accept the optional targeting fields `segment_percent` and `segmentation_conditions`, and both are returned on read. Only a single-configuration `GET` returns the read-only inline `payload` values (`{}` when unset) — list items and the create, update, and status responses omit them.

<Note>
  Both payload endpoints (`payload` and `payload-mapping`) are **full replace**: the object you send becomes the complete stored value. To change one key, read the current object, modify it, and send the whole object back. An empty object `{}` clears it. Payload value requests are limited to 64 KiB.
</Note>

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).