Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven/llms.txt

Use this file to discover all available pages before exploring further.

The Settings API gives you programmatic control over the entire Riven configuration, which is modelled by AppModel. You can read the current state, push partial updates, retrieve the JSON Schema for validation, and export or import configuration files. All routes are prefixed with /api/v1/settings and require a valid API key.

​
Schema endpoints

​
GET /settings/schema

Returns the full JSON Schema for AppModel. Useful for building configuration UIs or validating payloads before sending them to the update endpoints. 
curl http://localhost:8080/api/v1/settings/schema \
  -H "x-api-key: YOUR_KEY"
The response is a complete JSON Schema object describing every setting, its type, default value, and nested structure.

​
GET /settings/schema/keys

Returns a filtered JSON Schema that covers only the top-level keys you specify. Ideal for fetching the schema for a single section without downloading the entire document.
​
keys
string
required
Comma-separated list of top-level AppModel field names. Example: version,api_key,updaters.
​
title
string
default:"FilteredSettings"
Title field of the returned schema object.
curl "http://localhost:8080/api/v1/settings/schema/keys?keys=version,api_key" \
  -H "x-api-key: YOUR_KEY"
Returns 400 if any of the requested keys do not exist in AppModel.

​
Read settings

​
GET /settings/get/all

Returns the complete current settings as an AppModel JSON object. Every field is included, including nested sub-models. 
curl http://localhost:8080/api/v1/settings/get/all \
  -H "x-api-key: YOUR_KEY"
Abbreviated example response 
{
  "version": "0.18.0",
  "debug": false,
  "api_key": "a1b2c3d4e5f6...",
  "downloaders": {
    "real_debrid": {
      "enabled": true,
      "api_key": "RD_KEY_HERE"
    }
  }
}

​
GET /settings/get/

Read one or more specific settings by dot-separated path. Multiple paths can be requested by separating them with commas.
​
paths
string
required
Comma-separated list of dot-notation paths. Example: downloaders.real_debrid.enabled or version,debug.
curl http://localhost:8080/api/v1/settings/get/version \
  -H "x-api-key: YOUR_KEY"
Example response 
{
  "downloaders.real_debrid.enabled": true
}

​
Update settings

​
POST /settings/set/all

Replace settings with a deeply-merged update. The supplied JSON object is recursively merged into the existing settings — nested keys not included in the request body are preserved.
​
(body)
object
required
A partial or full AppModel JSON object. Any key present in the body overwrites the current value; omitted keys are unchanged.
curl -X POST http://localhost:8080/api/v1/settings/set/all \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "downloaders": {
      "real_debrid": {
        "enabled": true,
        "api_key": "YOUR_REAL_DEBRID_KEY"
      }
    }
  }'
Response 
{
  "message": "All settings updated successfully!"
}
Returns 400 if the resulting merged object fails AppModel validation.

​
POST /settings/set/

Update one or more specific settings by dot-notation path. Each path must have a corresponding entry in the request body.
​
paths
string
required
Comma-separated dot-notation paths to update. Example: downloaders.real_debrid.enabled.
​
(body)
object
required
An object whose keys are the same dot-notation paths and whose values are the new settings values.
curl -X POST \
  "http://localhost:8080/api/v1/settings/set/downloaders.real_debrid.enabled" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"downloaders.real_debrid.enabled": true}'
Returns 400 if a path does not exist in the current settings or if the new value fails validation.

​
Persistence

​
GET /settings/load

Reloads the settings from disk, discarding any in-memory changes that have not been saved. Useful after manually editing the settings file. 
curl http://localhost:8080/api/v1/settings/load \
  -H "x-api-key: YOUR_KEY"
Response: {"message": "Settings loaded!"}

​
POST /settings/save

Persists the current in-memory settings to disk. 
curl -X POST http://localhost:8080/api/v1/settings/save \
  -H "x-api-key: YOUR_KEY"
Response: {"message": "Settings saved!"}
The set/all and set/{paths} endpoints automatically call save after a successful update, so you normally do not need to call this endpoint directly.

Build docs developers (and LLMs) love

Get started for freeTalk to us