> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference/management/update-the-configuration.md).

# Update the configuration

Updates the service configuration in memory. The `config_json_string` field contains, serialized as a JSON string, the parameters to change; the parameters that are not included keep their value.

Not every parameter returned by `GET /api/v1/iad/config` can be changed with this endpoint. The following table shows the access of each one:

| Parameter                               | Access     |
| --------------------------------------- | ---------- |
| `metrics_saturation_queue_p95_ms`       | Read-write |
| `metrics_saturation_min_inflight_ratio` | Read-write |
| `metrics_error_rate_warning`            | Read-write |
| `metrics_idle_rps_threshold`            | Read-write |
| `metrics_quality_alert_window_seconds`  | Read-write |
| `port`                                  | Read-only  |
| `number_of_threads`                     | Read-only  |
| `connection_timeout`                    | Read-only  |
| `keep_alive_request_number`             | Read-only  |
| `client_max_body_size`                  | Read-only  |
| `logger_path`                           | Read-only  |
| `logger_file_prefix`                    | Read-only  |
| `logger_level`                          | Read-only  |
| `logger_rotation`                       | Read-only  |
| `logger_max_files`                      | Read-only  |
| `metrics_enabled`                       | Read-only  |
| `engine_url`                            | Read-only  |
| `engine_connection_timeout`             | Read-only  |
| `engine_request_timeout`                | Read-only  |
| `engine_max_retries`                    | Read-only  |
| `engine_retry_delay`                    | Read-only  |
| `engine_verify_ssl`                     | Read-only  |
| `engine_verbose`                        | Read-only  |
| `engine_pool_size`                      | Read-only  |
| `engine_health_max_age_seconds`         | Read-only  |

* Read-write parameters are applied without restarting the service. When the equivalent environment variable is defined (for example `FACEPHI_IAD_REST_METRICS_ERROR_RATE_WARNING`), its value prevails over the one sent. A value that cannot be parsed, or that is negative, is discarded with a warning in the log.
* The `metrics_*` parameters are the thresholds `GET /api/v1/iad/metrics` uses to classify the service state; they do not change how captures are evaluated.
* Read-only parameters are only configured at startup, through `config.json` or the `FACEPHI_IAD_REST_*` and `FACEPHI_IAD_ENGINE_*` environment variables. If they are sent to this endpoint, the request responds 200 and `GET` returns the value sent, but the service keeps using the value it started with.
* `GET` returns the values defined in `config.json` and those sent to this endpoint; it does not reflect values set through environment variables.
* Changes are not saved to `config.json` and are lost when the service restarts.
* JWT authentication settings (`auth_*`) are startup-only: `GET` does not return them and this endpoint rejects with 400 any request that includes them.

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"tags":[{"name":"Management","description":"Service management and monitoring endpoints"}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT signed with HS256 and sent as `Authorization: Bearer <jwt>`. Only required when JWT authentication is enabled."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT sent in the API key header. `x-api-key` is the default header name; it can be overridden at startup with `auth_api_key_header_name`. Only required when JWT authentication is enabled."}},"schemas":{"ConfigUpdateRequest":{"type":"object","required":["config_json_string"],"properties":{"config_json_string":{"type":"string","description":"JSON string with the configuration parameters to change. Only the read-write parameters listed in `POST /api/v1/iad/config` are applied. JWT authentication settings (`auth_*`) are rejected and can only be set at startup."}}},"MessageResult":{"type":"object","properties":{"message":{"type":"string","description":"Response message of the service."}}},"BadRequestResult":{"type":"object","description":"The request is not valid, the capture could not be processed, or the license of the service is not valid.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Service error message or error normalized by Facephi.","oneOf":[{"$ref":"#/components/schemas/FacephiErrorMessage"},{"type":"string"}]},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"FacephiErrorMessage":{"type":"string","description":"Documented public error messages returned in HTTP 400 responses.\n\n- Capture that the analysis engine could not evaluate (the three capture endpoints): `NoneBecause*` values.\n- Capture rejected by the experimental replay mitigation (the three capture endpoints): `Replay attack detected`.\n- Unclassified failure of the analysis engine: `ErrorProcessing` (`POST /api/v1/iad/evaluate` and `POST /api/v1/iad/evaluate/custom`) or `ErrorFacialImage` (`POST /api/v1/iad/extract`).\n- License that stopped being valid while the service runs (the three capture endpoints): `Invalid license: <reason> (code: <code>)`. The capture is not analyzed.\n- Request validation on the three capture endpoints: `Empty multipart payload`, `Required multipart field 'capture' not found` and `Empty data in multipart field 'capture'`.\n- Request validation specific to `POST /api/v1/iad/evaluate/custom`: the `pipeline` and `calibration` messages.\n- Service not ready: `Service not initialized` and `Service not configured`.\n\nWhen the analysis engine does not respond, the capture endpoints answer HTTP 503 with `Engine communication error:` followed by the detail (see `ServiceUnavailableResult`). `GET /api/v1/iad/health` answers HTTP 503 when the service cannot handle evaluations.\n","enum":["NoneBecauseFaceTooClose","NoneBecauseFaceNotFound","NoneBecauseFaceTooSmall","NoneBecauseAngleTooLarge","NoneBecauseImageDataError","NoneBecauseLicenseError","NoneBecauseTooManyFaces","NoneBecauseFaceTooCloseToBorder","NoneBecauseFaceCropped","NoneBecauseFaceOccluded","NoneBecauseEyesClosed","Replay attack detected","ErrorProcessing","ErrorFacialImage","Empty multipart payload","Required multipart field 'capture' not found","Empty data in multipart field 'capture'","Required multipart field 'pipeline' not found","Invalid value for 'pipeline'; expected 'iad_r01' or 'iad_r00'","Invalid value for 'calibration'; expected 'regular' or 'hardened'","Service not initialized","Service not configured"]},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."},"UnauthorizedResult":{"type":"object","description":"The authentication token is missing or invalid.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Reason for the rejection (`Missing authentication token`, `Authentication secret is not configured`, `JWT token is expired`, `JWT token is not yet valid`, `JWT token does not include exp claim` or `JWT token validation failed`). Use the HTTP status code, not the text, to make decisions."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"ExceptionResult":{"type":"object","description":"An unhandled internal error occurred.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Description of the internal error."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}}},"responses":{"Unauthorized":{"description":"The authentication token is missing or invalid. Only returned when JWT authentication is enabled. The response includes the `WWW-Authenticate` header with the value `Bearer`.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}}}},"paths":{"/api/v1/iad/config":{"post":{"summary":"Update the configuration","description":"Updates the service configuration in memory. The `config_json_string` field contains, serialized as a JSON string, the parameters to change; the parameters that are not included keep their value.\n\nNot every parameter returned by `GET /api/v1/iad/config` can be changed with this endpoint. The following table shows the access of each one:\n\n| Parameter | Access |\n|---|---|\n| `metrics_saturation_queue_p95_ms` | Read-write |\n| `metrics_saturation_min_inflight_ratio` | Read-write |\n| `metrics_error_rate_warning` | Read-write |\n| `metrics_idle_rps_threshold` | Read-write |\n| `metrics_quality_alert_window_seconds` | Read-write |\n| `port` | Read-only |\n| `number_of_threads` | Read-only |\n| `connection_timeout` | Read-only |\n| `keep_alive_request_number` | Read-only |\n| `client_max_body_size` | Read-only |\n| `logger_path` | Read-only |\n| `logger_file_prefix` | Read-only |\n| `logger_level` | Read-only |\n| `logger_rotation` | Read-only |\n| `logger_max_files` | Read-only |\n| `metrics_enabled` | Read-only |\n| `engine_url` | Read-only |\n| `engine_connection_timeout` | Read-only |\n| `engine_request_timeout` | Read-only |\n| `engine_max_retries` | Read-only |\n| `engine_retry_delay` | Read-only |\n| `engine_verify_ssl` | Read-only |\n| `engine_verbose` | Read-only |\n| `engine_pool_size` | Read-only |\n| `engine_health_max_age_seconds` | Read-only |\n\n- Read-write parameters are applied without restarting the service. When the equivalent environment variable is defined (for example `FACEPHI_IAD_REST_METRICS_ERROR_RATE_WARNING`), its value prevails over the one sent. A value that cannot be parsed, or that is negative, is discarded with a warning in the log.\n- The `metrics_*` parameters are the thresholds `GET /api/v1/iad/metrics` uses to classify the service state; they do not change how captures are evaluated.\n- Read-only parameters are only configured at startup, through `config.json` or the `FACEPHI_IAD_REST_*` and `FACEPHI_IAD_ENGINE_*` environment variables. If they are sent to this endpoint, the request responds 200 and `GET` returns the value sent, but the service keeps using the value it started with.\n- `GET` returns the values defined in `config.json` and those sent to this endpoint; it does not reflect values set through environment variables.\n- Changes are not saved to `config.json` and are lost when the service restarts.\n- JWT authentication settings (`auth_*`) are startup-only: `GET` does not return them and this endpoint rejects with 400 any request that includes them.\n","operationId":"updateConfig","tags":["Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateRequest"}}}},"responses":{"200":{"description":"Configuration updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResult"}}}},"400":{"description":"The body has no `config_json_string` string field, `config_json_string` does not contain a valid JSON object or includes JWT authentication settings, or the service is not initialized. When `config_json_string` cannot be loaded, the configuration does not change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"An unhandled internal error occurred; for example, the request body is JSON but not an object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}}}}}}
```