Jobs API

These routes expose async orchestration, polling, cancellation, cleanup, and campaign-level aggregation.

Generic Job Control

Method	Path	Purpose	Auth
GET	/jobs	list persisted jobs, newest first	yes
GET	/jobs/{job_id}	inspect one job result or in-flight status	yes
POST	/jobs/{job_id}/cancel	request cancellation of a queued or running task	yes
DELETE	/jobs/{job_id}	remove one job record from active registry	yes
POST	/jobs/cleanup	delete job records by age and/or terminal status	yes

Ingestion and Processing Jobs

Method	Path	Purpose	Auth
POST	/jobs/nc-to-geotiff	queue long-running NetCDF or OPeNDAP conversion	yes
POST	/jobs/merge-terrain	queue merge plus optional terrain generation	yes
POST	/jobs/mago-terrain	queue mago terrain generation	yes
POST	/jobs/repair-csw-metadata	refresh CSW metadata in background for datasets	yes

HySpex Campaign and Repair Jobs

Method	Path	Purpose	Auth
POST	/jobs/hyspex-csw-parent	queue one HySpex parent batch with cursor and campaign metadata	yes
GET	/jobs/hyspex-csw-campaigns/{campaign_id}	aggregate progress across all parent batches and child jobs in one campaign	no
POST	/jobs/hyspex-missing-variants	queue repair jobs for missing RGB or Z dataset variants	yes

Campaign-Specific Behavior

• campaign_id groups sequential parent batches into one logical ingestion campaign.
• campaign_total_children is optional and improves operator-facing progress summaries.
• start_position is the deterministic cursor used to continue later batches without reprocessing earlier result pages.
• The aggregate route reports totals, child job status counts, latest batch metadata, and next_start_position when available.

Practical Usage

• For long campaigns, keep requests sequential rather than concurrent at the parent-batch level.
• Poll the aggregate campaign endpoint rather than inferring progress from raw child jobs alone.
• Use cancellation sparingly and expect partial child completion if a campaign is interrupted mid-batch.