Client Configuration API

get_config

Get the current system configuration.

config = client.get_config()

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Returns: ConfigResponse — the persisted shared Config fields plus deployment-specific response overlays. Every shared nested type is linked in the accordion below.

For Enterprise, ConfigResponse also carries the response-only offline_tuner_config overlay. Its complete shape is { "enabled": false }. enabled: true is accepted on a prepared deployment — managed and self-hosted alike. Until a deployment's configuration reset has run it is rejected with config_reset_incomplete, which clears without action from you; deployment_unsupported is returned only when DEPLOYMENT_MODE is not a recognised value.

Enabling tuning is necessary but not sufficient. A check compares sessions that went well against sessions that did not, so it needs session outcomes.

Reporting them with mark_session_outcome is the direct way. Where you do not, Reflexio can infer an outcome from its own stored success evaluations, for sessions a playbook was actually used in.

Your report always wins. An inferred outcome is a placeholder: reporting your own outcome for the session replaces it (see mark_session_outcome), and an inferred outcome never replaces yours. Once you have reported an outcome for a session, a different answer for it is rejected. Reflexio judges a session as soon as the user has replied after a playbook was used in it, or after about ten minutes of quiet, so inferred outcomes arrive within minutes rather than days.

So an organization that reports no outcomes and has no evaluated traffic will see checks complete and no version ever published. See Playbook Tuning.

Example:

config = client.get_config()
print(config.profile_extractor_config.extraction_definition_prompt)
print(config.user_playbook_extractor_config.extraction_definition_prompt)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

set_config

Set the system configuration with replacement semantics. The Python client accepts a Config instance or a dict that validates as the shared Config model. It strips deployment-specific response overlays from Config model instances, including objects returned by get_config. Dictionary inputs are validated strictly and reject response overlays. A raw HTTP request is normalized by the active server configurator, so Enterprise accepts its normalized response overlays in a full replacement payload. Unknown fields are rejected. Omitted fields that have model defaults are reset to those defaults, so use update_config for partial changes.

Retrieval experiment fields are lifecycle-owned. A full save that omits them preserves their current values, while attempts to change them through set_config or update_config return 409. Use the retrieval experiment methods instead.

response = client.set_config(config)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Returns: dict with success and message keys.

Partial changes: use update_config for targeted edits such as applying a preset.

response = client.update_config({
    "extraction_preset": "long_form",  # auto-sets window_size=25, stride_size=10
})

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/update_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "extraction_preset": "long_form"
}
JSON

Example — full configuration:

config = client.get_config()

# Configure profile extraction
config.profile_extractor_config = {
    "extraction_definition_prompt": "Extract user preferences and interests",
    "context_prompt": "Analyzing customer conversations",
}

# Add playbook configuration with aggregation and deduplication
config.user_playbook_extractor_config = {
    "extraction_definition_prompt": "Extract playbook entries about response quality",
    "aggregation_config": {
        "min_cluster_size": 3,
        "clustering_similarity": 0.6,
    },
    "deduplication_config": {
        "search_threshold": 0.4,
        "search_top_k": 5,
    },
}

response = client.set_config(config)
print(f"Config updated: {response['success']}")

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

update_config

Apply a partial (PATCH-style) update to the org config. Unlike set_config, this does not round-trip the payload through Config(**...) client-side, so partial updates succeed without re-sending required fields like storage_config. The server fetches the existing config and shallow-merges atomically — there is no client-side read-modify-write race.

Nested objects (e.g. storage_config, llm_config) are replaced wholesale; deep merging is intentionally not supported. Raises TypeError if the argument is not a dict.

response = client.update_config({"shadow_mode_enabled": True})

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/update_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "shadow_mode_enabled": true
}
JSON

Returns: dict with success and msg keys.

invalidate_cache

Explicitly evict the server-side per-org Reflexio cache entry. Useful when the running config has been mutated through a channel the server can't observe (sibling-replica writes, direct DB updates, hand-edited config files). Most cases are handled automatically; this is the manual escape hatch.

Cross-org invalidation is not supported — the endpoint only ever invalidates the caller's own org.

response = client.invalidate_cache()

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/admin/cache/invalidate" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

Returns: dict {"invalidated": bool, "org_id": str}. The invalidated flag is False when nothing was cached for the org (still a successful no-op).

Identity & Storage Routing

Two read-only endpoints expose information about the organization and storage backing the current API key. Hosted Enterprise users commonly use them to verify where a key is routed.

whoami

Return the server's view of the caller's org and storage routing. The response is masked — it never contains raw credentials, so it is safe to print or include in bug reports.

identity = client.whoami()
print(identity.org_id, identity.storage_type, identity.storage_label)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/whoami" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

get_my_config

Return the raw storage credentials for the caller's org. Used by reflexio config pull / config storage to let users move per-org server-side config to a fresh machine.

my_config = client.get_my_config()
if my_config.success:
    print(my_config.storage_type)
    # my_config.storage_config is a dict containing raw credentials

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/my_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"