Skip to main content

Settings

Endpoints for managing system settings and configuration.

Authentication​

Most settings endpoints require admin authorization.

EndpointAuth Level
GET /api/settings/*Admin (most)
PUT /api/settings/*Admin
GET /api/healthPublic
GET /api/readyPublic
GET /api/system/statusPublic

System health​

Returns the health status of the application and its dependencies.

GET /api/health

Response codes​

CodeDescription
200Healthy
503Unhealthy (one or more services failing)

Response schema​

{
  "status": "string",
  "version": "string",
  "checks": {
    "database": {
      "status": "string",
      "responseTime": "number"
    },
    "downloadClients": {
      "status": "string",
      "clients": [
        {
          "id": "string",
          "name": "string",
          "status": "string"
        }
      ]
    },
    "indexers": {
      "status": "string",
      "enabledCount": "integer",
      "totalCount": "integer"
    }
  },
  "timestamp": "string"
}

Status values​

StatusDescription
healthyService is functioning normally
degradedService is working with issues
unhealthyService is not functioning

Example request​

curl http://localhost:3000/api/health

Example response​

{
  "status": "healthy",
  "version": "2.1.0",
  "checks": {
    "database": {
      "status": "healthy",
      "responseTime": 15.2
    },
    "downloadClients": {
      "status": "healthy",
      "clients": [
        {
          "id": "c10e8400-e29b-41d4-a716-446655440030",
          "name": "qBittorrent",
          "status": "healthy"
        }
      ]
    },
    "indexers": {
      "status": "healthy",
      "enabledCount": 5,
      "totalCount": 8
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Readiness check​

Returns whether the application is ready to accept traffic.

GET /api/ready

Response codes​

CodeDescription
200Ready
503Not ready

Response schema​

{
  "ready": "boolean",
  "timestamp": "string"
}

System status​

Returns detailed status of background services.

GET /api/system/status

Response schema​

{
  "services": [
    {
      "name": "string",
      "status": "string",
      "lastRun": "string",
      "nextRun": "string",
      "uptime": "number"
    }
  ],
  "timestamp": "string"
}

Service status values​

StatusDescription
pendingService not yet started
startingService is initializing
readyService is running normally
errorService encountered an error

List settings​

Returns all system settings.

GET /api/settings

Response codes​

CodeDescription
200Success
401Authentication required
403Admin authorization required

Response schema​

{
  "settings": [
    {
      "key": "string",
      "value": "any",
      "type": "string",
      "category": "string",
      "description": "string",
      "updatedAt": "string"
    }
  ]
}

Get setting​

Returns a specific setting value.

GET /api/settings/:key

Path parameters​

ParameterTypeDescription
keystringSetting key

Response codes​

CodeDescription
200Success
401Authentication required
403Admin authorization required
404Setting not found

Response schema​

{
  "key": "string",
  "value": "any",
  "type": "string",
  "category": "string",
  "description": "string",
  "updatedAt": "string"
}

Update setting​

Updates a system setting.

PUT /api/settings/:key

Path parameters​

ParameterTypeDescription
keystringSetting key

Request body schema​

FieldTypeRequiredDescription
valueanyYesNew setting value

Response codes​

CodeDescription
200Success
400Invalid value
401Authentication required
403Admin authorization required
404Setting not found

Response schema​

{
  "success": "boolean",
  "key": "string",
  "value": "any",
  "updatedAt": "string"
}

Example request​

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-key: cinephage_your_key_here" \
  -d '{"value": true}' \
  http://localhost:3000/api/settings/autoUnmonitorPreviouslyDownloadedMovies

TMDB settings​

Get TMDB settings​

GET /api/settings/tmdb

Response schema​

{
  "apiKey": "string",
  "language": "string",
  "certificationCountry": "string",
  "useSsl": "boolean",
  "cacheEnabled": "boolean",
  "cacheTtl": "integer"
}

Update TMDB settings​

PUT /api/settings/tmdb

Request body schema​

FieldTypeRequiredDescription
apiKeystringNoTMDB API key
languagestringNoPreferred language
certificationCountrystringNoCertification country code
useSslbooleanNoUse SSL connections
cacheEnabledbooleanNoEnable response caching
cacheTtlintegerNoCache TTL in seconds

Filter settings​

Get filter settings​

GET /api/settings/filters

Response schema​

{
  "minimumSeeders": "integer",
  "retention": "integer",
  "rssSyncInterval": "integer",
  "enableCompletedDownloadHandling": "boolean",
  "removeCompletedDownloads": "boolean",
  "removeFailedDownloads": "boolean"
}

Update filter settings​

PUT /api/settings/filters

Request body schema​

FieldTypeRequiredDescription
minimumSeedersintegerNoMinimum seeders for torrents
retentionintegerNoMaximum age in days
rssSyncIntervalintegerNoRSS sync interval in minutes
enableCompletedDownloadHandlingbooleanNoAuto-process completed downloads
removeCompletedDownloadsbooleanNoRemove from client when complete
removeFailedDownloadsbooleanNoRemove from client when failed

External URL settings​

Get external URL​

GET /api/settings/external-url

Response schema​

{
  "externalUrl": "string",
  "basePath": "string",
  "useSsl": "boolean"
}

Update external URL​

PUT /api/settings/external-url

Request body schema​

FieldTypeRequiredDescription
externalUrlstringNoExternal access URL
basePathstringNoBase path for reverse proxy
useSslbooleanNoUse SSL in generated URLs

API key management​

List API keys​

GET /api/settings/system/api-keys

Response codes​

CodeDescription
200Success
401Authentication required
403Admin authorization required

Response schema​

{
  "keys": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "createdAt": "string",
      "lastUsedAt": "string"
    }
  ]
}

Generate API key​

POST /api/settings/system/api-keys

Request body schema​

FieldTypeRequiredDescription
namestringYesKey name
typestringYesKey type (main, streaming)

Response schema​

{
  "success": "boolean",
  "key": {
    "id": "string",
    "name": "string",
    "type": "string",
    "value": "string",
    "createdAt": "string"
  }
}
warning

The value field is only returned on creation. Save it securely as it cannot be retrieved again.

Regenerate API key​

POST /api/settings/system/api-keys/:id/regenerate

Invalidates the old key and generates a new one.

Response schema​

{
  "success": "boolean",
  "key": {
    "id": "string",
    "value": "string",
    "updatedAt": "string"
  }
}

Log streaming​

SSE endpoint for real-time log streaming.

GET /api/settings/logs/stream

Response format​

Server-Sent Events stream with log entries.

Event format​

event: log
data: {"level":"info","message":"...","timestamp":"...","source":"..."}

Log levels​

LevelDescription
debugDebug information
infoInformational messages
warnWarning messages
errorError messages

Download logs​

Downloads the log file.

GET /api/settings/logs/download

Response codes​

CodeDescription
200Success (file download)
401Authentication required
403Admin authorization required

Setting categories​

CategoryDescription
generalGeneral application settings
mediaMedia management settings
downloadDownload client settings
indexerIndexer settings
notificationNotification settings
uiUser interface settings
securitySecurity and authentication settings

See Also​