Skip to main content

Tasks

Endpoints for managing scheduled monitoring tasks in Cinephage. Tasks handle automated operations like searching for missing content, upgrades, and subtitle searches.

Authentication​

All task endpoints require authentication via session cookie or API key.

EndpointAuth Level
GET /api/tasksrequireAuth
GET /api/tasks/streamrequireAuth
POST /api/tasks/:taskId/runrequireAuth
POST /api/tasks/:taskId/cancelrequireAuth
PUT /api/tasks/:taskId/enabledrequireAuth
PUT /api/tasks/:taskId/intervalrequireAuth
GET /api/tasks/:taskId/historyrequireAuth
GET /api/tasks/history/:historyId/activityrequireAuth

List tasks​

Returns all available monitoring tasks.

GET /api/tasks

Request parameters​

None required.

Response codes​

CodeDescription
200Success
401Authentication required

Response schema​

{
  "tasks": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "type": "monitoring | subtitle | system",
      "enabled": "boolean",
      "interval": "integer",
      "intervalUnit": "minutes | hours | days",
      "defaultInterval": "integer",
      "lastRunAt": "string",
      "nextRunAt": "string",
      "status": "idle | running | queued | error",
      "supportsCancel": "boolean",
      "supportsHistory": "boolean"
    }
  ]
}

Task types​

TypeDescription
monitoringContent monitoring tasks (search, upgrade)
subtitleSubtitle-related tasks
systemSystem maintenance tasks

Built-in tasks​

TaskTypeDescription
CutoffUnmetmonitoringSearch for items below quality cutoff
UpgrademonitoringSearch for quality upgrades
MissingEpisodesmonitoringSearch for missing TV episodes
NewEpisodesmonitoringDetect new episodes
PendingReleasesmonitoringMonitor pending releases
MissingSubtitlessubtitleSearch for missing subtitles
SubtitleUpgradesubtitleSearch for better subtitles
SubtitleSearchOnImportsubtitleSearch subtitles on media import
HistoryCleanupsystemClean up old history entries (30 days)

Example request​

curl -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/tasks"

Example response​

{
  "tasks": [
    {
      "id": "task_missing_subtitles",
      "name": "Missing Subtitles",
      "description": "Search for missing subtitles on media items",
      "type": "subtitle",
      "enabled": true,
      "interval": 360,
      "intervalUnit": "minutes",
      "defaultInterval": 360,
      "lastRunAt": "2024-06-20T10:00:00Z",
      "nextRunAt": "2024-06-20T16:00:00Z",
      "status": "idle",
      "supportsCancel": true,
      "supportsHistory": true
    },
    {
      "id": "task_upgrade",
      "name": "Quality Upgrade",
      "description": "Search for better quality releases",
      "type": "monitoring",
      "enabled": true,
      "interval": 10080,
      "intervalUnit": "minutes",
      "defaultInterval": 10080,
      "lastRunAt": "2024-06-19T02:00:00Z",
      "nextRunAt": "2024-06-26T02:00:00Z",
      "status": "idle",
      "supportsCancel": true,
      "supportsHistory": true
    }
  ]
}

Task Events Stream​

Real-time SSE stream for task status updates.

GET /api/tasks/stream

Response​

Server-Sent Events stream with task status changes.

Event types​

EventDescription
task:startedTask execution started
task:progressTask progress update
task:completedTask execution completed
task:errorTask execution failed
task:cancelledTask was cancelled

Example event​

event: task:started
data: {"taskId":"task_upgrade","timestamp":"2024-06-20T10:00:00Z"}

Run task​

Triggers immediate execution of a task.

POST /api/tasks/:taskId/run

Request parameters​

ParameterTypeRequiredDescription
taskIdstringYesTask identifier

Request body schema​

FieldTypeRequiredDescription
forcebooleanNoForce run even if already running
optionsobjectNoTask-specific options

Response codes​

CodeDescription
200Task started or already running
401Authentication required
404Task not found

Example request​

curl -X POST \
  -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/tasks/task_upgrade/run"

Example response​

{
  "success": true,
  "taskId": "task_upgrade",
  "executionId": "exec_abc123",
  "message": "Task queued for execution"
}

Cancel task​

Cancels a running task.

POST /api/tasks/:taskId/cancel

Request parameters​

ParameterTypeRequiredDescription
taskIdstringYesTask identifier

Response codes​

CodeDescription
200Cancellation successful
400Task not running or doesn't support cancellation
401Authentication required
404Task not found

Example request​

curl -X POST \
  -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/tasks/task_upgrade/cancel"

Example response​

{
  "success": true,
  "taskId": "task_upgrade",
  "message": "Task cancellation requested"
}

Toggle task enabled​

Enables or disables a task.

PUT /api/tasks/:taskId/enabled

Request body schema​

FieldTypeRequiredDescription
enabledbooleanYesEnable or disable task

Response codes​

CodeDescription
200Task updated
401Authentication required
404Task not found

Example request​

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-key: cinephage_your_key_here" \
  -d '{"enabled": false}' \
  "http://localhost:3000/api/tasks/task_missing_subtitles/enabled"

Update task interval​

Changes the execution interval for a task.

PUT /api/tasks/:taskId/interval

Request body schema​

FieldTypeRequiredDescription
intervalintegerYesNew interval value
unitstringYesUnit: minutes, hours, or days

Response codes​

CodeDescription
200Interval updated
400Invalid interval or unit
401Authentication required
404Task not found

Example request​

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-key: cinephage_your_key_here" \
  -d '{"interval": 720, "unit": "minutes"}' \
  "http://localhost:3000/api/tasks/task_missing_subtitles/interval"

Example response​

{
  "success": true,
  "taskId": "task_missing_subtitles",
  "interval": 720,
  "intervalUnit": "minutes",
  "nextRunAt": "2024-06-20T22:00:00Z"
}

Get task history​

Returns execution history for a task.

GET /api/tasks/:taskId/history

Request parameters​

ParameterTypeRequiredDescription
taskIdstringYesTask identifier

Query parameters​

ParameterTypeRequiredDescription
pageintegerNoPage number (default: 1)
limitintegerNoItems per page (default: 20)
statusstringNoFilter by status: completed, failed, cancelled

Response schema​

{
  "history": [
    {
      "id": "string",
      "taskId": "string",
      "startedAt": "string",
      "completedAt": "string",
      "duration": "integer",
      "status": "completed | failed | cancelled",
      "itemsProcessed": "integer",
      "itemsAffected": "integer",
      "error": "string"
    }
  ],
  "pagination": {
    "page": "integer",
    "limit": "integer",
    "total": "integer",
    "totalPages": "integer"
  }
}

Example request​

curl -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/tasks/task_missing_subtitles/history?limit=10"

Get task history activity​

Returns detailed per-item activity for a task execution.

GET /api/tasks/history/:historyId/activity

Request parameters​

ParameterTypeRequiredDescription
historyIdstringYesHistory entry identifier

Query parameters​

ParameterTypeRequiredDescription
pageintegerNoPage number (default: 1)
limitintegerNoItems per page (default: 50)

Response schema​

{
  "activity": [
    {
      "id": "string",
      "historyId": "string",
      "mediaId": "string",
      "mediaTitle": "string",
      "action": "string",
      "status": "string",
      "message": "string",
      "timestamp": "string"
    }
  ],
  "pagination": {
    "page": "integer",
    "limit": "integer",
    "total": "integer",
    "totalPages": "integer"
  }
}

Example request​

curl -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/tasks/history/exec_abc123/activity?limit=50"

See Also​