--- title: "Create a new job" method: POST path: "/jobs" tags: ["Jobs"] --- # Create a new job `POST /jobs` ## Request - Base URL: `https://localhost/index.php/api` - URL: `https://localhost/index.php/api/jobs` - Auth: API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Enqueue a new background job for processing ## Request body - JobCreateRequest - `job_type` 'generate_pdf' | 'generate_microdata_resource' | 'import_microdata' | 'import_indicator_data' | 'publish_project' | 'hello_world', required: Registered background job type identifier - `payload` union, required: Job-specific parameters validated by the handler for job_type - GeneratePdfJobPayload: Payload for PDF generation job (used in generic /jobs endpoint) - `project_id` integer, required: Project ID for which to generate the PDF - `options` object: Optional PDF generation options - `template` string: PDF template to use (optional) - `format` string: PDF format options (optional) - GenerateMicrodataResourceJobPayload: Payload for generate_microdata_resource job (used in generic /jobs endpoint) - `project_id` integer, required: Project ID (sid) - `export_format` string, required: csv, dta, sav, xpt, or json - `export_version` string: Stata version when export_format is dta - `file_ids` string[] - `zip` boolean - `overwrite` boolean - `resource_id` integer: Regenerate an existing generated resource - `refresh_description` boolean - `max_wait_seconds` integer - ImportMicrodataJobPayload: Payload for microdata import job - `file_id` string, required: File ID of the uploaded data file to import - `project_id` string, required: Project ID where the data will be imported - ImportIndicatorDataJobPayload: Payload for import_indicator_data job (used in generic /jobs endpoint) - `project_id` integer, required: Project sid - `upload_id` string, required: Completed resumable upload ID - `indicator_value` string, required - `delimiter` string - `keep_extra_csv_columns` boolean - PublishProjectJobPayload: Payload for publish_project job (used in generic /jobs endpoint) - `project_id` union, required - integer - string - `catalog_connection_id` integer, required - `user_id` integer, required: User performing the publish (set automatically by convenience endpoint) - `publish_metadata` boolean - `publish_thumbnail` boolean - `publish_resources` boolean - `publish_dsd` boolean - `dsd_overwrite` boolean - `publish_indicator_data` boolean - `delete_nada_resources` boolean - `options` object - HelloWorldJobPayload: Payload for hello_world job (testing/demo; POST /jobs only) - `message` string: Optional greeting message - `priority` integer: Job priority - `max_attempts` integer: Maximum retry attempts ## Response `201` Job created successfully - JobCreateResponse - `status` string - `message` string - `uuid` string - `job` Job: Job object - `uuid` string - `job_type` 'generate_pdf' | 'generate_microdata_resource' | 'import_microdata' | 'import_indicator_data' | 'publish_project' | 'hello_world': Registered background job type identifier - `status` 'pending' | 'held' | 'processing' | 'completed' | 'failed': Current job status - `priority` integer: Job priority - `user_id` integer: User who initiated the job (NULL for system jobs) - `payload` union: Job-specific parameters; shape depends on job_type (see *JobPayload schemas) - GeneratePdfJobPayload: Payload for PDF generation job (used in generic /jobs endpoint) - `project_id` integer, required: Project ID for which to generate the PDF - `options` object: Optional PDF generation options - `template` string: PDF template to use (optional) - `format` string: PDF format options (optional) - GenerateMicrodataResourceJobPayload: Payload for generate_microdata_resource job (used in generic /jobs endpoint) - `project_id` integer, required: Project ID (sid) - `export_format` string, required: csv, dta, sav, xpt, or json - `export_version` string: Stata version when export_format is dta - `file_ids` string[] - `zip` boolean - `overwrite` boolean - `resource_id` integer: Regenerate an existing generated resource - `refresh_description` boolean - `max_wait_seconds` integer - ImportMicrodataJobPayload: Payload for microdata import job - `file_id` string, required: File ID of the uploaded data file to import - `project_id` string, required: Project ID where the data will be imported - ImportIndicatorDataJobPayload: Payload for import_indicator_data job (used in generic /jobs endpoint) - `project_id` integer, required: Project sid - `upload_id` string, required: Completed resumable upload ID - `indicator_value` string, required - `delimiter` string - `keep_extra_csv_columns` boolean - PublishProjectJobPayload: Payload for publish_project job (used in generic /jobs endpoint) - `project_id` union, required - integer - string - `catalog_connection_id` integer, required - `user_id` integer, required: User performing the publish (set automatically by convenience endpoint) - `publish_metadata` boolean - `publish_thumbnail` boolean - `publish_resources` boolean - `publish_dsd` boolean - `dsd_overwrite` boolean - `publish_indicator_data` boolean - `delete_nada_resources` boolean - `options` object - HelloWorldJobPayload: Payload for hello_world job (testing/demo; POST /jobs only) - `message` string: Optional greeting message - `result` union: Job result when completed; shape depends on job_type (see *JobResult schemas) - GeneratePdfJobResult: Result returned when PDF generation job completes successfully - `pdf_path` string: File path to the generated PDF - `project_id` integer: Project ID for which the PDF was generated - `generated_at` string, date-time: Timestamp when PDF was generated - GenerateMicrodataResourceJobResult: Result returned when microdata resource generation job completes - `status` 'success' | 'skipped' - `project_id` integer - `export_format` string - `resource_id` integer - `filename` string - `links_count` integer - `message` string: Present when status is skipped (resource already exists) - ImportMicrodataJobResult: Result returned when microdata import job completes successfully - `fastapi_job_id` string: FastAPI processing job ID - `file_id` string: File ID that was imported - `project_id` union: Project ID where data was imported - string - integer - `datafile_path` string: Path to the processed data file - `variables_imported` integer: Number of variables imported from the data dictionary - `case_count` integer, nullable: Row count from the data dictionary - `csv_file` string, nullable: Basename of the CSV file after cleanup - `fastapi_status` string - `message` string - ImportIndicatorDataJobResult: Result returned when indicator data import job completes successfully - `status` string - `indicator_value` string - `job_id` string: FastAPI replace-from-csv job ID - PublishProjectJobResult: Result returned when publish_project job completes - `results` object: Per-step publish outcomes (metadata, thumbnail, resources, dsd, etc.) - `errors` object: Non-fatal step errors keyed by step name - `project_id` union - integer - string - `catalog_connection_id` integer - `published_at` string, date-time - HelloWorldJobResult: Result returned when hello_world job completes - `message` string - `processed_at` string, date-time - `job_id` integer: Internal job queue ID - `error_message` string: Error details if job failed - `attempts` integer: Number of processing attempts - `max_attempts` integer: Maximum retry attempts - `created_at` string, date-time: Job creation timestamp - `started_at` string, date-time: Job processing start timestamp (null if not started) - `completed_at` string, date-time: Job completion timestamp (null if not completed) - `worker_id` string: Worker identifier processing this job (null if not processing) ## Other responses - `400`: Bad request (invalid job type or payload) ## Changes - **2026-06-06** `7f334b22fc50`: 6 breaking, 6 warning, 7 info - request property `job_type` was restricted to a list of enum values - the `payload` request property type changed from `object` to no type - added `#/components/schemas/GeneratePdfJobPayload, #/components/schemas/GenerateMicrodataResourceJobPayload, #/components/schemas/ImportMicrodataJobPayload, #/components/schemas/ImportIndicatorDataJobPayload, #/components/schemas/PublishProjectJobPayload, #/components/schemas/HelloWorldJobPayload` to the `job/payload` response property `oneOf` list for the response status `201` - added `#/components/schemas/GeneratePdfJobResult, #/components/schemas/GenerateMicrodataResourceJobResult, #/components/schemas/ImportMicrodataJobResult, #/components/schemas/ImportIndicatorDataJobResult, #/components/schemas/PublishProjectJobResult, #/components/schemas/HelloWorldJobResult` to the `job/result` response property `oneOf` list for the response status `201` - …15 more - **2026-05-24** `1ff58dcd71a4`: 1 warning - added the new `held` enum value to the `job/status` response property for the response status `201` [Operation history](https://skmtc.dev/worldbank/apis/metadata-editor-jobs-api/changes/jobs/post.md) --- [API](https://skmtc.dev/worldbank/apis/metadata-editor-jobs-api.md) - [All operations](https://skmtc.dev/worldbank/apis/metadata-editor-jobs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/worldbank/apis/metadata-editor-jobs-api/revisions/755536b6492e?raw)