Skip to content

Tdarr v2 API Reference

Base URL: http://<host>:8265/api/v2

All POST endpoints use Content-Type: application/json. Request bodies wrapped in { "data": { ... } }.

Server Status

GET /status

Returns status of server.

Response: 200 — Object with status, isProduction, os, version, buildDate, uptime

Database (CRUD)

POST /cruddb

Interact with the Tdarr database.

Collections: - FileJSONDB — Scanned files - LibrarySettingsJSONDB — Library configurations - StatisticsJSONDB — Statistics - NodeJSONDB — Node configurations - SettingsGlobalJSONDB — Global settings - StagedJSONDB — Staged files - F2FOutputJSONDB — File-to-file output - FlowsJSONDB — Flow configurations

Modes:

Mode Required Fields Description
insert collection, docID, obj Insert document
getById collection, docID Get single document
getAll collection Get all documents
update collection, docID, obj Update document keys
removeOne collection, docID Remove single document
removeAll collection Remove all documents

Request: 

{
  "data": {
    "collection": "LibrarySettingsJSONDB",
    "mode": "getAll"
  }
}

POST /search-db

Returns array of files.

Request: 

{
  "data": {
    "string": "sample",
    "lessThanGB": 10,
    "greaterThanGB": 0
  }
}

POST /search-plugins

Returns array of plugins.

Request: 

{
  "data": {
    "string": "ffmpeg",
    "pluginType": "Community"
  }
}

POST /search-flow-plugins

Searches for flow plugins.

Request: 

{
  "data": {
    "string": "transcode",
    "pluginType": "Community"
  }
}

POST /search-flow-templates

Searches for flow templates.

Request: 

{
  "data": {
    "string": "h265",
    "pluginType": "Community"
  }
}

Nodes

GET /get-nodes

Returns all nodes.

Response: 200 — Object

POST /update-node

Updates a node.

Request: 

{
  "data": {
    "nodeID": "InternalNode",
    "nodeUpdates": {}
  }
}

POST /restart-node

Restarts a node.

Request: 

{
  "data": {
    "nodeID": "InternalNode"
  }
}

POST /disconnect-node

Force disconnects a node.

POST /poll-worker-limits

Polls worker limits and queue lengths for a node.

File Scanning

POST /scan-files

Scans files.

Request: 

{
  "data": {
    "scanConfig": {}
  }
}

POST /scan-individual-file

Scans a single file.

Request: 

{
  "data": {
    "scanTypes": {
      "exifToolScan": true,
      "mediaInfoScan": true,
      "hasVideoStream": true,
      "ffprobeScan": true
    },
    "filePath": "/media/video/file.mkv",
    "dbID": "library-id-here"
  }
}

POST /get-filescanner-status

Gets file scanner status for a database.

POST /kill-file-scanner

Kills the file scanner for a database.

Workers

POST /cancel-worker-item

Cancels a worker item.

POST /kill-worker

Kills a worker.

POST /alter-worker-limit

Change worker type limits.

Request: 

{
  "data": {
    "nodeID": "InternalNode",
    "workerType": "transcodecpu",
    "workerLimit": 2
  }
}

Files

POST /delete-file

Deletes a file.

POST /delete-unhealthy-files

Deletes unhealthy files from a table.

POST /remove-library-files

Removes all files from a library.

POST /set-all-status

Sets status of all records in a table.

Libraries & Scheduling

POST /toggle-folder-watch

Toggles folder watch status.

POST /toggle-schedule

Toggles schedule of a file or folder.

POST /update-schedule-block

Updates schedule block status.

POST /remove-library-files

Removes all files from a library.

Codec & Plugin Filtering

POST /add-video-codec-exclude

Adds a video codec exclude.

POST /update-video-codec-exclude

Updates a video codec exclude.

POST /remove-video-codec-exclude

Removes a video codec exclude.

POST /add-audio-codec-exclude

Adds an audio codec exclude.

POST /update-audio-codec-exclude

Updates audio codec exclude status.

POST /remove-audio-codec-exclude

Removes audio codec exclude status.

POST /add-plugin-include

Adds a plugin include.

POST /update-plugin-include

Updates plugin include status.

POST /remove-plugin-include

Removes plugin include status.

Plugins

POST /get-res-stats

Returns resource statistics.

POST /create-plugin

Creates a new plugin.

POST /read-plugin-text

Reads plugin text.

POST /save-plugin-text

Saves plugin text.

POST /delete-plugin

Deletes a plugin.

POST /copy-community-to-local

Copies community plugin to local.

POST /verify-plugin

Verifies a plugin.

POST /read-plugin

Reads a plugin file.

POST /update-plugins

Updates all plugins.

POST /sync-plugins

Syncs plugins.

GET /download-plugins

Downloads plugin zip file.

Backups

POST /get-backup-status

Get backup status.

POST /get-backups

Get backups.

POST /create-backup

Creates a backup file.

POST /delete-backup

Deletes a backup file.

POST /reset-backup-status

Resets backup status.

Other

POST /get-db-statuses

Returns statuses of all databases.

POST /get-time-now

Returns current time.

POST /verify-folder-exists

Verifies folder existence.

POST /get-subdirectories

Returns subdirectories of a folder.

POST /create-sample

Creates a sample file.

POST /run-help-command

Runs FFmpeg/HandBrake command.

POST /performance-stats

Returns performance stats.

POST /client-clienttype

Get client data.

POST /item-proc-end

Processing of item completed.

POST /transcode-user-verdict

Transcode user verdict.

POST /read-job-file

Reads a job file.

POST /list-footprintid-reports

Lists reports for a footprint ID.

GET /get-server-log

Returns server log file.

POST /get-node-log

Returns log file for a node.

Key Collections Schema

LibrarySettingsJSONDB

Libraries define source/output folders and scan config.

FlowsJSONDB

Flows define transcode pipelines (source filter → transcode → health check → output).

NodeJSONDB

Nodes define worker instances (CPU/GPU transcode workers, health check workers).

FileJSONDB

Scanned files with metadata (codec, size, duration, health status).

Typical Setup Flow (API)

  1. POST /cruddb — Insert library into LibrarySettingsJSONDB
  2. GET /get-nodes — Verify InternalNode registered
  3. POST /cruddb — Insert flow into FlowsJSONDB
  4. POST /scan-files — Trigger file scan on library
  5. Monitor via POST /get-db-statuses and POST /performance-stats