Guide
API
Guide
API

Built-in API

QLAPI is available to JavaScript/TypeScript and Python scripts through the panel's task preloader. It uses the local runtime rather than application-token HTTP OpenAPI or the remote CLI. Running a script with plain Node/Python does not guarantee this variable is injected.

This reference follows api.proto and preloader clients. JavaScript methods return Promises; Python methods synchronously return dictionaries. HTTP fields are not necessarily available in this API: for example, work_dir and allow_multiple_instances are absent from the current CronItem protocol.

Methods

Pass parameters as one object. Array fields require arrays, even for a single ID.

Method Purpose Parameter object Response type
getEnvs List environment variables { searchValue: string } EnvsResponse
createEnv Create environment variables { envs: EnvItem[] } EnvsResponse
updateEnv Update an environment variable { env: EnvItem } EnvResponse
deleteEnvs Delete environment variables { ids: int32[] } Response
moveEnv Move an environment variable { id: int32, fromIndex: int32, toIndex: int32 } EnvResponse
disableEnvs Disable environment variables { ids: int32[] } Response
enableEnvs Enable environment variables { ids: int32[] } Response
updateEnvNames Rename environment variables { ids: int32[], name: string } Response
getEnvById Get an environment variable { id: int32 } EnvResponse
systemNotify Send a notification { title: string, content: string, notificationInfo?: NotificationInfo } Response
getCronDetail Find a task by log path { log_path: string } CronDetailResponse
createCron Create a task { command: string, schedule: string, name?: string, labels: string[], sub_id?: int32, extra_schedules: ExtraScheduleItem[], task_before?: string, task_after?: string } CronResponse
updateCron Update a task { id: int32, command?: string, schedule?: string, name?: string, labels: string[], sub_id?: int32, extra_schedules: ExtraScheduleItem[], task_before?: string, task_after?: string } CronResponse
deleteCrons Delete tasks { ids: int32[] } Response
getCrons List tasks { searchValue?: string } CronsResponse
getCronById Get a task { id: int32 } CronResponse
enableCrons Enable tasks { ids: int32[] } Response
disableCrons Disable tasks { ids: int32[] } Response
runCrons Run tasks { ids: int32[] } Response

? marks optional protocol fields; server validation still applies. createCron requires command/schedule. Include the complete command and schedule when updating a task. getCronDetail looks up log_path, not a task ID.

Data types

EnvItem

{
  id?: number;
  name?: string;
  value?: string;
  remarks?: string;
  status?: number;
  position?: string;
}

CronItem

{
  id?: number;
  command?: string;
  schedule?: string;
  name?: string;
  labels: string[];
  sub_id?: number;
  extra_schedules: ExtraScheduleItem[];
  task_before?: string;
  task_after?: string;
  status?: number;
  log_path?: string;
  pid?: number;
  last_running_time?: string;
  last_execution_time?: string;
}

ExtraScheduleItem

{
  schedule: string;
}

Response

{
  code: number;
  message?: string;
}

EnvResponse

{
  code: number;
  data: EnvItem;
  message?: string;
}

EnvsResponse

{
  code: number;
  data: EnvItem[];
  message?: string;
}

CronResponse

{
  code: number;
  data: CronItem;
  message?: string;
}

CronsResponse

{
  code: number;
  data: CronItem[];
  message?: string;
}

CronDetailResponse

{
  code: number;
  data: CronItem;
  message?: string;
}

The JavaScript client decodes int64 as strings, including position and task time fields. Successful responses have code: 200; check the API code and handle call exceptions.

Notifications

systemNotify requires title and content. Optional notificationInfo overrides panel notification settings; omit it to use the panel configuration.

Supported notificationInfo.type values:

gotify, goCqHttpBot, serverChan, pushDeer, bark, chat, telegramBot, dingtalkBot, weWorkBot, weWorkApp, aibotk, iGot, pushPlus, wePlusBot, email, pushMe, feishu, webhook, chronocat, ntfy, wxPusherBot, wxPusherSpt, wpush.

Common fields: gotifyUrl/gotifyToken/gotifyPriority for Gotify, telegramBotToken/telegramBotUserId for Telegram, larkKey/larkSecret for Feishu, wxPusherSptList for WxPusher SPT, and wpushApiKey/wpushChannel/wpushTopicCode for WPush. See the notification protocol for the remaining fields.

Examples

JavaScript

async function main() {
  const envs = await QLAPI.getEnvs({ searchValue: 'EXAMPLE' });
  console.log(envs.code);
  const tasks = await QLAPI.getCrons({ searchValue: 'demo' });
  console.log(tasks.code);
  await QLAPI.systemNotify({ title: 'Demo', content: 'Task finished' });
}

main().catch(console.error);

Python

result = QLAPI.getCrons({"searchValue": "demo"})
print(result["code"])
QLAPI.systemNotify({"title": "Demo", "content": "Task finished"})