Batch jobs

Async multi-file processing via POST /v1/jobs. Upload several files, poll status, then download per-item output. Sync POST /v1/execute remains for single-file requests. Try Batch mode in the testing console.

When to use

Process up to N files for a batch-enabled tool (see catalog batch)
Avoid long HTTP timeouts — create returns 202 quickly; a worker processes items
Phase 1 tools: background_removal, image_processing, pdf_text_extraction, document_processing

Limits (defaults)

Max files: 10 (heavy image / PDF tools)
Per-file size: same as sync max_file_bytes
Max job total bytes: 200MB
Retention: 48 hours (then job files are deleted)
Worker concurrency: 1 item at a time (same host as API)

Create job

POST /v1/jobs · multipart · Authorization + Idempotency-Key

Field tool
Field files — one or more files (array)
Same tool parameter fields as execute

curl -X POST "$TOOLGRID_API_BASE/v1/jobs" \
  -H "Authorization: Bearer tg_api_YOUR_SECRET" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -F "tool=background_removal" \
  -F "useAI=false" \
  -F "files=@./a.png" \
  -F "files=@./b.png"

{
  "success": true,
  "request_id": "…",
  "job_id": "…",
  "status": "queued",
  "item_count": 2,
  "status_url": "/v1/jobs/{job_id}"
}

Poll status

GET /v1/jobs/:jobId — owner-scoped. Returns item statuses (no binary payloads).

Download output

GET /v1/jobs/:jobId/items/:index/output

Image / PDF tools: binary stream
JSON tools (e.g. PDF text): { success, result }

Cancel

DELETE /v1/jobs/:jobId cancels still-queued items. Running items finish or fail by lock policy.

Billing

Soft balance check on create (N × unit credits). Credits are reserved and settled (or refunded) per item when the worker claims each file — same wallet as sync execute.

Ops

Run the worker on the same host as the API (shared disk):

cd tg-backend && npm run worker:api-jobs

Data directory: API_JOBS_DATA_DIR (default ./data/api-jobs). Without a running worker, jobs stay queued.

Errors

BATCH_NOT_SUPPORTED
BATCH_LIMIT_EXCEEDED
JOB_NOT_FOUND / JOB_EXPIRED
JOB_ITEM_NOT_READY

Create job

POST /v1/jobs · multipart · Authorization + Idempotency-Key

Field tool

Field files — one or more files (array)

Same tool parameter fields as execute

curl -X POST "$TOOLGRID_API_BASE/v1/jobs" \
  -H "Authorization: Bearer tg_api_YOUR_SECRET" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -F "tool=background_removal" \
  -F "useAI=false" \
  -F "files=@./a.png" \
  -F "files=@./b.png"

{
  "success": true,
  "request_id": "…",
  "job_id": "…",
  "status": "queued",
  "item_count": 2,
  "status_url": "/v1/jobs/{job_id}"
}