Update the runtime configuration

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

Not every parameter returned by GET /api/v1/finger/config can be changed with this endpoint:

Parameter	Access
engine_url	Read and write
engine_connection_timeout	Read and write
engine_request_timeout	Read and write
engine_max_retries	Read and write
engine_retry_delay	Read and write
engine_verify_ssl	Read and write
engine_verbose	Read and write
metrics_saturation_queue_p95_ms	Read and write
metrics_saturation_min_inflight_ratio	Read and write
metrics_error_rate_warning	Read and write
metrics_idle_rps_threshold	Read and write
metrics_quality_alert_window_seconds	Read and 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_pool_size	Read only
auth_*	Rejected

• Read and write parameters are applied without restarting the service. When the equivalent environment variable is set (for example FACEPHI_FINGER_ENGINE_REQ_TIMEOUT or FACEPHI_FINGER_REST_METRICS_ERROR_RATE_WARNING), its value prevails over the one sent.

• The read and write engine_* parameters are only applied on master nodes; worker nodes accept them without effect.

• The metrics_* parameters are the thresholds GET /api/v1/finger/metrics uses to classify the service state and raise alerts. An invalid or negative value is discarded with a warning in the log and the previous source in the precedence order is used.

• Read only parameters are only configured at startup, through config.json or environment variables. If they are sent to this endpoint, the request answers 200 and GET returns the value sent, but the service keeps using the value it started with.

• Changes are not saved to config.json and are lost when the service restarts.

• JWT authentication settings (auth_*) are startup only: GET never returns them and this endpoint rejects any request that includes them with HTTP 400 and message equal to JWT auth settings are not accessible from the config endpoint.

Errors:

HTTP	Detail	Cause
400	Key config_json_string not found, Key config_json_string is not a string, Key config_json_string is empty string	config_json_string is missing, is not a string or is empty
400	JWT auth settings are not accessible from the config endpoint	config_json_string includes auth_* settings
500	Failed to load configuration from config_json_string	config_json_string does not contain a valid JSON object; the configuration does not change

post

Autorizações

AuthorizationstringObrigatório

HS256 JWT signed with auth_jwt_secret and carrying an exp claim, sent as Authorization: Bearer <jwt>. Accepted while auth_accept_authorization_header is true (default). Only enforced when auth_enabled is true.

Corpo

config_json_stringstringObrigatório

Parameters to change, serialized as a JSON object inside a string. Parameters that are not included keep their current value. JWT authentication settings (auth_*) are rejected.

Example: {"engine_request_timeout":45000,"metrics_error_rate_warning":0.1}

Respostas

200

Configuration updated successfully (Configuration updated successfully).

application/json

messagestringObrigatório

Service message.

400

The request is invalid or could not be processed. message carries the reason; see the operation description for the values it can take.

application/json

401

JWT authentication is enabled and the request carries no token or an invalid one. message is one of Missing authentication token, JWT token is expired, JWT token does not include exp claim, JWT token validation failed or, when auth_jwt_secret is empty, Authentication secret is not configured.

application/json

500

Unhandled internal error. exception carries the detail.

application/json

post/api/v1/finger/config

POST /api/v1/finger/config HTTP/1.1
Host: 127.0.0.1:6982/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "config_json_string": "{\"engine_request_timeout\":45000,\"metrics_error_rate_warning\":0.1}"
}

{
  "message": "Configuration updated successfully"
}