Script Management API Documentation#

Base Path#

/scripts

The full public API prefix is /open/scripts. The history endpoints and save behavior below require Qinglong 2.23.0 or newer and scripts permission. See script editing history for the panel workflow.

Endpoints#

Get Scripts List#

GET /

Query Parameters

{
  path?: string  // Script path
}

Notes

• Excludes blacklisted folders (node_modules, .git, etc.)
• Directories are sorted first

Get Script Details#

GET /detail

Query Parameters

{
  path?: string,  // Script path
  file: string    // File name
}

Upload/Create Script#

POST /

Request body: use the file field in multipart/form-data for uploads. Use JSON to create directories or create/save text content.

{
  file?: File,           // Uploaded file
  filename: string,      // File name
  path?: string,         // File path
  content?: string,      // File content
  originFilename?: string, // Original file name
  directory?: string,    // Directory name (for creating directories)
  skipHistory?: boolean, // Explicit confirmation to save unsupported content without history
  expectedHash?: string  // Required when skipHistory=true; current content SHA-256
}

File uploads, new files and directory creation do not create history automatically. Overwriting an existing script with JSON content preserves its previous content. Provide content for text saves; an empty string is allowed. When the debugger saves as another existing script, the destination's previous content enters history and the source is backed up before removal. Safe aliases pointing to the same script are handled as an in-place save.

Update Script Content#

PUT /

Request body (application/json)

{
  filename: string,  // File name
  path?: string,    // File path
  content: string,  // File content; an empty string is allowed
  skipHistory?: boolean,
  expectedHash?: string // Required when skipHistory=true; 64 hexadecimal SHA-256 characters
}

Use JSON to update an existing script's content and the POST endpoint above to upload a file. Changed content preserves the current version before saving; identical content does not add history.

Save and restore data fields depend on the result:

Only the first result includes cleanupPending. A value of true means the script was saved, but history quota cleanup is pending. Check data directory permissions and free space.

List script history#

GET /history

The query is { filename: string, path?: string }. History uses filename, unlike the existing GET /detail query's file.

Success returns { code: 200, data: { versions, currentHash, limit } }. Versions are newest first. limit is the maximum retained version count (20 by default), and currentHash is the SHA-256 of the content currently saved on the server.

Read historical and current content#

GET /history/detail

The query is { filename: string, path?: string, id: string }. id must be a version UUID returned by the list endpoint.

Success data is { version, current, currentHash }. version contains id, createdAt, source, hash and content, without the list's size or identical. current is the text saved on the server; it excludes unsaved editor changes.

Restore a history version#

PUT /history/restore

JSON request body

{
  filename: string,
  path?: string,
  id: string,           // Version UUID
  expectedHash: string  // currentHash from preview; 64 hexadecimal SHA-256 characters
}

Restoring preserves the current content first. If the file changed after preview, the server returns HTTP 409 and API code: 409. Read, compare and confirm again; do not replace the hash and retry automatically. Ordinary content saves do not require this hash, so this does not provide conflict protection for every edit.

History limits and failures#

History supports UTF-8 text up to 1 MiB, including empty files, without NUL or invalid UTF-8. Each script retains at most 20 previous versions. Uploads, new files, renames, deletions, subscription updates and external edits do not record history automatically. Renames do not migrate history, and history cannot recover deleted scripts.

Only a save returning HTTP 413 with top-level historyUnavailable: true and currentHash can be retried after explicit user confirmation with skipHistory: true and that expectedHash. The result reports that no history was recorded. A change during confirmation still returns 409. Other 413 failures from archive capacity limits, damaged history and permission errors cannot be bypassed this way.

Validation may return 400, and path/resource permission checks may return 403. Check both the HTTP status and API code. See script editing history for overall quotas, cleanup and complete backups.

Delete Script#

DELETE /

Request Body

{
  filename: string,  // File name
  path?: string,    // File path
  type?: string     // Type
}

Download Script#

POST /download

Request Body

{
  filename: string,  // File name
  path?: string,    // File path
}

Run Script#

PUT /run

Request Body

{
  filename: string,  // File name
  content?: string, // File content
  path?: string    // File path
}

This endpoint debugs the supplied content by writing and executing a temporary file in the same directory (for example, demo.swap.js for demo.js). Omitting content writes an empty file; it does not read the original script. To run a saved cron task, use PUT /open/crons/run in the Crontab API.

Stop Script#

PUT /stop

Request Body

{
  filename: string,  // File name
  path?: string,    // File path
  pid?: number      // Process ID
}

Rename Script#

PUT /rename

Request Body

{
  filename: string,    // Original file name
  path?: string,      // File path
  newFilename: string // New file name
}

Error Handling#

• All endpoints follow unified error handling mechanism
• Successful responses return { code: 200, data: ... }
• Error logging is handled by Winston logger

Notes#

• File uploads handled by multer
• File path security checks
• Supports file backup
• Automatic temporary file cleanup

Retired endpoint#

GET /open/scripts/:file returns API code 410. Use GET /open/scripts/detail with file and optional path instead.