Skip to main content
PerfectPalette
PerfectPalette HelpAdmin Scripts
Back to app

Admin Scripts

The Admin Scripts page (/admin/jobs) lets admins run and monitor background data-maintenance jobs. Each job is idempotent — safe to re-run — and its progress is tracked in real time.

Running a job

  1. Navigate to Admin → Jobs.
  2. Find the job in the catalog and click Run Now.
  3. The job appears at the top of the Job History table with status pending, then running.
  4. Progress updates stream automatically every few seconds. The page stops polling once all active jobs finish.

Available jobs

AI Tag Pairings

Generates AI-written descriptions and mood tags for pairings that are missing them. Only processes pairings where both the description and the tag fields are absent, so it is safe to run multiple times.

When to run: After bulk-importing new pairings, or periodically to catch any that slipped through.

Suggest Pairings

Scores all color pairs in the Lexicon using the pairing engine and seeds the top diverse candidates into the pairings table. Default settings keep the top 50 pairs with a minimum score of 60.

When to run: After adding a significant batch of new named colors to the Lexicon, or on a regular schedule to keep pairings fresh.

Sync Pairing Names

Resolves hex-value display names (e.g., #FF6B6B) to their accepted Lexicon name. Pairs that already have a resolved name are skipped by default — pass checkAll: true in the payload to recheck all pairs.

When to run: After approving a batch of new Lexicon names, to propagate those names into existing pairings.

Push Names to Lexicon

Writes curated pairing names back to the Lexicon for hex values that have no entry at all, or have only a low-quality auto-import name.

When to run: After a curation pass on pairings, to update the Lexicon with the improved names.

Auto-Name Pairings

Uses AI to generate name suggestions for pairing hex values that have no accepted Lexicon name. Suggestions are submitted for admin review — they are not auto-approved.

When to run: When the Lexicon has unnamed colors that appear in pairings, to seed the review queue with AI candidates.

extract-colors-from-image

Category: Explore Triggered by: Admin — Image Extract page (/admin/image-extract)

Records the result of an image color extraction. This job type is written retrospectively (not executed via the job runner) so that image extraction operations appear in the job history table for audit purposes. The job result payload contains:

  • paletteId — the created Explore Palette ID
  • pairingsCreated — number of pairings added
  • lexiconCandidatesCreated — number of hex values added to the Lexicon color table
  • imageName — original filename of the uploaded image
  • colorCount — number of confirmed colors saved

Scheduled triggers (cron)

Jobs can also be triggered automatically by an external scheduler (e.g. Railway cron, cron-job.org) via:

POST /api/cron/<job-type>
Authorization: Bearer <CRON_SECRET>

The CRON_SECRET environment variable must be set on the server. A correct secret returns 202 with the new job ID; an incorrect secret returns 401.

Example job types for the URL path: ai-tag-pairings, suggest-pairings, sync-pairing-names, push-pairing-names, auto-name-pairings.

Job history

The history table shows every job execution with its status, attempt count, and any error message. Use the status filter to narrow to failed jobs when investigating issues. Failed jobs can be retried from the history table.