REST API Configuration Reference

This reference lists the REST API’s operating modes, environment variables, defaults and signing-key requirements. It serves developers and deployment maintainers configuring the API. Command syntax is documented in dioptra-api Command Reference; Python construction and overrides are documented in REST API Application Factory Reference.

Operating Modes

The API requires an explicit operating mode. The dioptra-api dev and dioptra-api prod commands select their corresponding modes regardless of an inherited DIOPTRA_RESTAPI_ENV value. Python callers can select the mode through an argument or that environment variable; see Mode Precedence.

Mode policies

Property	dev	prod
Packaged server	Flask development server.	Gunicorn.
Platforms	POSIX and native Windows.	POSIX only.
Debugging default	Enabled; may be disabled.	Disabled; enabling it is rejected.
Authentication	Enabled; may be disabled explicitly.	Enabled; disabling it is rejected.
CORS	Enabled for the configured origin.	The development CORS configuration is not applied.
Signing key	An existing persistent key file is required.	An existing protected key file is required.

Debug flags and server selection do not infer a mode. Missing, empty or unsupported modes fail configuration validation.

Environment Variables

The API reads these variables when resolving a configuration. Later environment changes affect subsequent resolution, not an existing application. Python callers can supply typed overrides with higher priority.

Boolean values accept case-insensitive true, false, 1 and 0, ignoring surrounding whitespace. Empty or other boolean values are invalid. Integer settings accept whole numbers, such as 1000; decimal fractions (1000.0) and scientific notation (1e3) are not accepted.

Mode and Key Selection

Variable	Default	Accepted values
DIOPTRA_RESTAPI_ENV	None.	dev or prod; required when the caller does not select a mode.
DIOPTRA_RESTAPI_SECRET_KEY_FILE	~/.local/share/dioptra/restapi/secret-key	A nonempty path to an existing key; see Signing-Key Files.

Authentication and Cookies

Variable	Default	Accepted values
DIOPTRA_LOGIN_DISABLED	false	Boolean; true is rejected in production.
DIOPTRA_SESSION_PROTECTION	strong	Case-insensitive basic, strong or none; none disables session protection.
DIOPTRA_REMEMBER_COOKIE_DURATION	1209600 seconds.	Integer duration in seconds.
DIOPTRA_REMEMBER_COOKIE_SECURE	false	Boolean.

API Presentation and Pagination

Variable	Default	Accepted values
DIOPTRA_CORS_ORIGIN	http://localhost:5173	Nonempty origin string; used in development.
DIOPTRA_SWAGGER_PATH	/	Flask-RESTX documentation-path string.
DIOPTRA_BASE_URL	Unset.	Nonempty string passed as Flask-RESTX’s url_scheme; this is a scheme, not a full base URL.
DIOPTRA_MAX_PAGE_SIZE	1000	Integer of at least 10.

Connections and Logging

Variable	Default	Accepted values
DIOPTRA_RESTAPI_DATABASE_URI	Absolute SQLite URI for dioptra.db in the invocation directory.	Nonempty SQLAlchemy database URI used in both API modes.
RQ_REDIS_URI	redis://	Nonempty Redis URI with the redis, rediss or unix scheme.
MLFLOW_TRACKING_URI	MLflow’s get_tracking_uri() result.	Nonempty SDK-supported URI passed to the API’s MLflow client.
DIOPTRA_RESTAPI_LOG_AS_JSON	false	Boolean.
DIOPTRA_RESTAPI_LOG_LEVEL	INFO	Python logging level name; normalized to uppercase.

Signing-Key Files

API startup reads an existing key; it never creates a key, repairs its permissions or selects a fallback file after a failure. Use dioptra-api init-key to provision it before startup. Keep the file out of source control and avoid displaying its contents in output or logs.

Path and Content

Property	Requirement
Path resolution	Expand ~ and normalize relative paths against the invocation directory without following symbolic links. Embedded environment-variable expressions are not expanded.
File contents	Exactly 64 lowercase ASCII hexadecimal characters, optionally followed by one LF.
Key generation	The hexadecimal text represents 32 cryptographically random bytes. Format validation does not establish the entropy of supplied material.
Flask value	The 64-character text, without the optional LF, is used as SECRET_KEY.

Filesystem Requirements

Platform	Startup requirements
POSIX	The effective API account owns the immediate parent with mode 0700 and the regular, single-link file with mode 0400 or 0600. Symlinks in the file or parent path are rejected. Protected read-only files and volume mounts are supported.
Native Windows development	The same content format and detectable link/file-type checks apply. POSIX ownership, permissions and no-follow descriptor enforcement are unavailable; owner-only Windows ACLs are not established.
Native Windows production	Unsupported.

Missing, unreadable, malformed or unsafe key files stop startup. The initializer’s permission repairs and interrupted-initialization behavior are documented in init-key.

Retired Environment Variables

The presence of either variable below causes an error, even when its replacement or a Python override is supplied. Diagnostics identify setting names without printing credential values.

Retired variable	Replacement
DIOPTRA_DEPLOY_SECRET_KEY	Provision a key file and select its path with DIOPTRA_RESTAPI_SECRET_KEY_FILE.
DIOPTRA_RESTAPI_DEV_DATABASE_URI	DIOPTRA_RESTAPI_DATABASE_URI in every operating mode.