# @exellix/jobs-api > Exellix jobs HTTP API — Fastify REST server and programmatic read/write queries over the job queue. Queue runtime is @exellix/jobs; dashboard is @exellix/jobs-ui; persistence is @exellix/jobs-db. Latest version **1.2.0** (published 2026-07-11) · exellix-license license · 941 weekly downloads ## Install ```sh npm install @exellix/jobs-api pnpm add @exellix/jobs-api yarn add @exellix/jobs-api bun add @exellix/jobs-api ``` Provides the command `exellix-jobs-api`. ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score; growing popularity. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.2.0 | | Published | 2026-07-11 | | First published | 2026-06-22 | | Weekly downloads | 941 | | License | exellix-license | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 25 | | Unpacked size | 1 MB | | Known vulnerabilities | 0 (+2 in 1 direct dependencies) | | Install scripts | no | | Maintainers | exellix | | Keywords | exellix, jobs, api, fastify | ## Links - npm: https://www.npmjs.com/package/@exellix/jobs-api - Repository: https://github.com/exellix/exellix-engine-mono-repo - Homepage: https://github.com/exellix/exellix-engine-mono-repo#readme - Issues: https://github.com/exellix/exellix-engine-mono-repo/issues - npm.io page: https://npm.io/package/@exellix/jobs-api ## Dependencies (25) - [fastify](https://npm.io/package/fastify.md) ^5.9.0 - [@exellix/jobs](https://npm.io/package/@exellix/jobs.md) ^1.1.0 - [@x12i/helpers](https://npm.io/package/@x12i/helpers.md) ^2.1.0 - [@fastify/helmet](https://npm.io/package/@fastify/helmet.md) ^13.0.2 - [@fastify/static](https://npm.io/package/@fastify/static.md) ^9.1.3 - [@exellix/jobs-db](https://npm.io/package/@exellix/jobs-db.md) ^1.1.0 - [@exellix/ai-tasks](https://npm.io/package/@exellix/ai-tasks.md) ^10.15.15 - [@x12i/ai-profiles](https://npm.io/package/@x12i/ai-profiles.md) ^4.3.0 - [@x12i/memorix-mongo](https://npm.io/package/@x12i/memorix-mongo.md) 1.32.0 - [@exellix/error-intel](https://npm.io/package/@exellix/error-intel.md) ^1.0.2 - [@x12i/memorix-agents](https://npm.io/package/@x12i/memorix-agents.md) 1.32.0 - [@x12i/memorix-hippox](https://npm.io/package/@x12i/memorix-hippox.md) 1.33.0 - [@x12i/memorix-schema](https://npm.io/package/@x12i/memorix-schema.md) 1.32.0 - [@x12i/memorix-writer](https://npm.io/package/@x12i/memorix-writer.md) 1.33.0 - [@exellix/graph-engine](https://npm.io/package/@exellix/graph-engine.md) ^9.7.0 - [@x12i/memorix-pipeline](https://npm.io/package/@x12i/memorix-pipeline.md) 1.33.0 - [@exellix/catalox-graphs](https://npm.io/package/@exellix/catalox-graphs.md) ^1.5.0 - [@exellix/job-dispatcher](https://npm.io/package/@exellix/job-dispatcher.md) ^1.0.11 - [@x12i/memorix-assembler](https://npm.io/package/@x12i/memorix-assembler.md) 1.32.0 - [@x12i/memorix-retrieval](https://npm.io/package/@x12i/memorix-retrieval.md) 1.33.0 - [@x12i/memorix-schema-api](https://npm.io/package/@x12i/memorix-schema-api.md) 1.8.0 - [@x12i/memorix-descriptors](https://npm.io/package/@x12i/memorix-descriptors.md) 1.32.0 - [@exellix/catalox-ai-skills](https://npm.io/package/@exellix/catalox-ai-skills.md) ^1.0.6 - [@x12i/memorix-explorer-api](https://npm.io/package/@x12i/memorix-explorer-api.md) 1.32.1 - [@exellix/catalox-graphs-http](https://npm.io/package/@exellix/catalox-graphs-http.md) ^1.2.0 ## Alternatives - [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads - [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads - [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads - [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads - [@nest-batch/kubernetes](https://npm.io/package/@nest-batch/kubernetes.md) — 143 weekly downloads ## Recent versions - 1.2.0 (latest) — 2026-07-11 - 1.1.0 — 2026-07-11 - 1.0.20 — 2026-07-10 - 1.0.19 — 2026-07-07 - 1.0.18 — 2026-07-07 - 1.0.17 — 2026-07-07 - 1.0.16 — 2026-07-05 - 1.0.15 — 2026-07-05 - 1.0.14 — 2026-07-05 - 1.0.13 — 2026-07-05 - 1.0.12 — 2026-06-30 - 1.0.10 — 2026-06-26 - 1.0.9 — 2026-06-26 - 1.0.7 — 2026-06-24 - 1.0.6 — 2026-06-24 - … 3 more at https://npm.io/package/@exellix/jobs-api/versions ## README # @exellix/jobs-api **Jobs HTTP API** — Fastify REST server and programmatic query library over the Exellix job queue. Handles enqueue, retry, cancel, job-def CRUD, work-factory routes, Memorix record views, and inline worker execution. | Package | Role | |---------|------| | [`@exellix/jobs`](../jobs/README.md) | Jobs **manager** — queue runtime, worker loop, CLI | | **`@exellix/jobs-api`** (this) | Jobs **HTTP API** — REST + programmatic queries | | [`@exellix/jobs-ui`](../jobs-ui/README.md) | Jobs **dashboard** — React operator SPA | | [`@exellix/jobs-db`](../jobs-db/README.md) | Jobs **data tier** — Mongo persistence | > A **JobRun** is one graph run on one input. See [`temp/jobs/`](../temp/jobs/README.md) for the design. ## Install ```bash npm install @exellix/jobs-api @exellix/jobs-db @exellix/jobs ``` ## Quick start ```bash # MONGO_URI must be set (or in ../../graph-packages/graph-engine/.env) npm run dev # build + serve on :3099 npm run serve # serve already-built dist/ ``` Set `PORT` to override default `3099`. Set `LOG_LEVEL=debug` for verbose Fastify logs. ### Serving the dashboard The API can optionally serve the built `@exellix/jobs-ui` static bundle on the same port (same-origin `/api` for the SPA): 1. Build the UI: `cd ../jobs-ui && npm run build` 2. Start the API — it auto-detects `../jobs-ui/dist`, or set `JOBS_UI_STATIC_DIR=/path/to/jobs-ui/dist` For local dev with HMR, run the full stack (API + worker + UI) with one command: ```bash # from jobs-ui or repo root npm run dev # jobs-ui — runs scripts/dev-jobs.mjs npm run dev:jobs # repo root ``` Or run API and UI in separate terminals: ```bash # terminal 1 cd jobs-api && npm run serve # terminal 2 cd jobs-ui && npm run dev:ui # Vite on :5190, proxies /api → :3099 ``` ## Deployment posture | Variable | Default | Effect | |----------|---------|--------| | `JOBS_UI_TOKEN` | unset | When set, all `/api/*` routes require `Authorization: Bearer ` | | `JOBS_UI_STATIC_DIR` | auto-detect sibling `jobs-ui/dist` | Path to built dashboard static files | | `WORK_FACTORY_POLL_INTERVAL_MS` | inherits `JOBS_POLL_INTERVAL_MS` | Continuous work evaluation interval (ms) | | `WORK_EVAL_BATCH_SIZE` | `500` | Max records enqueued per evaluation tick | | `JOBS_WORKER_CONCURRENCY` | app `maxConcurrentJobs` (default **10**) | Parallel run slots in inline worker | | `WOREX_GRAPH_CONCURRENCY` | **4** | Parallel task nodes per graph run | | `ACTIVIX_STORAGE_MODE` | `database` (recommended) | Mongo-only Activix; avoids silent `playground/` folder fallback | | `MONGO_LOGS_URI` | falls back to `MONGO_URI` | Activix logs database connection | ## Activix observability Graph runs and per-node activity are persisted to **Mongo via Activix** (`exellix-graph-runs`, `exellix-node-activity`). The Live Console in jobs-ui reads `GET /api/factory-runs/:id/activities` — backed by `getActivixClient().getJobActivities()`, not local files. Set `ACTIVIX_STORAGE_MODE=database` in `.env` (see `.env.example`). With the default Activix `automatic` mode, a unreachable Mongo connection causes Activix to write debug artifacts under `playground/` in the process cwd — safe to delete; they are not used by the API or UI. AI task phases (`@exellix/ai-tasks`) use a separate Activix client (default collection `task-activities`); the same `ACTIVIX_STORAGE_MODE` env applies. ## HTTP API All routes are under `/api` (legacy unprefixed aliases may also exist). See the route tables in the previous combined README — full listing preserved in [`docs/handoff/jobs-ui.md`](../docs/handoff/jobs-ui.md). Key groups: runs/stats, job-defs, enqueue, settings/queue admission, entities/records/sources, work-factory (work, batches, on-demand, factory-runs), catalox graphs, memorix agents proxy. ### Processing layer — context preview, associated enrichment, coverage These routes use `@exellix/jobs` resolution helpers. They do **not** dispatch graphs or write associated data unless a separate operational job does so. | Method | Path | Purpose | |--------|------|---------| | `POST` | `/api/context/preview` | Preview runtime `jobMemory` for one input + optional `contextSources` / Hippox links. Body: `{ input, sourceEntity?, contextSources?, contextLinks?, hippoxContext? }` | | `POST` | `/api/associated-enrichment/preview` | Preview persistent associated* smart-merge for one source record — **no Memorix write**. Body: `{ recordId, input, existingAssociatedValue?, config: AssociatedEnrichmentConfig }` | | `POST` | `/api/graph/input-coverage` | Sample records from a batch list; report assembly gaps and per-context-source coverage (resolved / missing / filtered / mandatory failures). Body: `{ graphId, selection, recordIds, contextSources?, sourceEntity?, sampleSize? }` | | `POST` | `/api/graphs/execute` | Sync graph execute. When `contextSources` is set, resolves `jobMemory` before dispatch (Graph Studio / host clients). Body adds: `contextSources?`, `sourceEntity?`, `recordId?` | Related assembler routes (unchanged): `GET /api/assembler/properties`, `POST /api/assembler/preview`. ## Programmatic queries ```ts import { createJobRunStore } from '@exellix/jobs-db'; import { listRuns, getRun, recentFailures, throughputStats } from '@exellix/jobs-api'; const { store } = await createJobRunStore({ mongoUri: process.env.MONGO_URI }); await listRuns(store, { status: 'pending', page: 1 }); await recentFailures(store, { limit: 10 }); ``` ## Scripts ```bash npm run build # tsc → dist/ npm test # unit tests (HTTP + queries) npm run test:live # live Mongo integration npm run serve # production server npm run queue-worker npm run clean-jobs # interactive wipe of job runs / batches / evaluations npm run cancel-jobs # interactive cancel of pending/running runs npm run bind:catalox npm run provision:catalox-graphs # descriptor 1.1.0 (graphKind indexes) npm run provision:catalox-graphs:full # provision + backfill graph rows ``` ### CLI (`exellix-jobs-api`) ```bash exellix-jobs-api serve exellix-jobs-api queue-worker [--worker-id=...] [--concurrency=...] [--verbose] # Queue health exellix-jobs-api status [--batch=] [--mongo] [--json] exellix-jobs-api settings show exellix-jobs-api settings set --queue-mode=running|paused [--max-concurrent=] # Batch operations exellix-jobs-api preview-batch --entity= --graph= [--collection=snapshots] exellix-jobs-api queue-batch --file=batch.json [--yes] exellix-jobs-api queue-single --entity= --record= --graph= # Recovery workflow (retry failed runs in place, then drain) exellix-jobs-api retry-runs --batch= --status=failed [--error-contains=MongoNetwork] --yes exellix-jobs-api drain [--concurrency=] [--verbose] exellix-jobs-api watch --batch= [--interval=5000] exellix-jobs-api complete-batch --batch= --yes --verbose # Maintenance exellix-jobs-api clean-jobs [--yes] [--dry-run] exellix-jobs-api cancel-jobs [--yes] [--status=pending] ``` **Recover a batch after transient Mongo failures** (same graph/batch, no re-queue): ```bash # One-shot orchestration: resume → retry failed → drain → watch exellix-jobs-api complete-batch \ --batch=33b6919c-efea-4156-b3a3-30f1f7f8e926 \ --yes --verbose # Or step-by-step: exellix-jobs-api settings set --queue-mode=running exellix-jobs-api retry-runs --batch=33b6919c-... --status=failed --yes exellix-jobs-api drain --verbose exellix-jobs-api watch --batch=33b6919c-... ``` Global flags: `--yes` / `-y`, `--dry-run`, `--json`, `--verbose`, `-h` / `--help`. `clean-jobs` removes all factory job runs, batch records, and work evaluation history from the runtime Mongo DB. Continuous work definitions, queue settings, and Memorix data are kept. Requires `MONGO_URI` (loads `.env` from the current directory or `jobs-api/.env` when run from the monorepo root). ## Backlog Deferred items: [backlog/README.md](./backlog/README.md) ## License exellix-license --- _Source: https://npm.io/package/@exellix/jobs-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._