--- title: Jobs API - Notehub API Reference description: The Notehub jobs API provides RESTful methods that can be used to manage batch jobs. source_url: https://dev.blues.io/api-reference/notehub-api/jobs-api/ canonical_url: https://dev.blues.io/api-reference/notehub-api/jobs-api/ markdown_url: https://dev.blues.io/api-reference/notehub-api/jobs-api.md --- # Jobs API The Notehub jobs API provides RESTful methods that can be used to manage [batch jobs](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | Name | HTTP Request | | --------------------------------- | -------------------------------------------------------------------------- | | [Get Jobs](#get-jobs) | **GET** `/v1/projects/{projectOrProductUID}/jobs` | | [Create Job](#create-job) | **POST** `/v1/projects/{projectOrProductUID}/jobs` | | [Get Job](#get-job) | **GET** `/v1/projects/{projectOrProductUID}/jobs/{jobUID}` | | [Delete Job](#delete-job) | **DELETE** `/v1/projects/{projectOrProductUID}/jobs/{jobUID}` | | [Run Job](#run-job) | **POST** `/v1/projects/{projectOrProductUID}/jobs/{jobUID}/run` | | [Get Job Runs](#get-job-runs) | **GET** `/v1/projects/{projectOrProductUID}/jobs/{jobUID}/runs` | | [Get Job Run](#get-job-run) | **GET** `/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}` | | [Cancel Job Run](#cancel-job-run) | **POST** `/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}/cancel` | | [Delete Job Run](#delete-job-run) | **DELETE** `/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}` | ## Get Jobs (Notehub) List all [batch jobs](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs) for a project. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments None **Example** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//jobs' -H 'Authorization: Bearer ' ``` **Response Members** ### `jobs` *array of objects* An array of batch job objects. Each object contains the following fields: ### `jobs.job_uid` *string* The globally-unique identifier of the batch job. ### `jobs.name` *string* The name of the batch job. ### `jobs.created` *UNIX Epoch time* The time the job was created. ### `jobs.created_by` *string* The email address of the user who created the job. Example Response ```json { "jobs": [ { "job_uid": "00000000-0000-0000-0000-000000000000", "name": "My Batch Job", "created": 1750773741, "created_by": "User Name" } ] } ``` ## Create Job (Notehub) Create a new [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `POST` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | developer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments ### `name` *string (required)* A name for the batch job. This argument must be provided in the query string. ### `body` *object (required)* The [job definition](https://dev.blues.io/notehub/notehub-walkthrough.md#batch-job-json-format) as a JSON object. This object must be provided as the request's body. **Example** **Bash** ```bash curl -X POST -L 'https://api.notefile.net/v1/projects//jobs?name=' -H 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '' ``` **Response Members** ### `job_uid` *string* The globally-unique identifier of the newly created batch job. Example Response ```json { "job_uid": "00000000-0000-0000-0000-000000000000" } ``` ## Get Job (Notehub) Get details on a [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `jobUID` - The globally-unique identifier of a batch job. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments None **Example** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//jobs/' -H 'Authorization: Bearer ' ``` **Response Members** ### `job_uid` *string* The globally-unique identifier of the batch job. ### `name` *string* The name of the batch job. ### `created` *UNIX Epoch time* The time the job was created. ### `created_by` *string* The user who created the job. ### `definition` *object* The [job definition](https://dev.blues.io/notehub/notehub-walkthrough.md#batch-job-json-format). Structure varies by job type. Example Response ```json { "job_uid": "00000000-0000-0000-0000-000000000000", "name": "My Batch Job", "created": 1750773741, "created_by": "User Name", "definition": {} } ``` ## Delete Job (Notehub) Delete a [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `DELETE` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `jobUID` - The globally-unique identifier of a batch job. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | developer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments None **Example** **Bash** ```bash curl -X DELETE -L 'https://api.notefile.net/v1/projects//jobs/' -H 'Authorization: Bearer ' ``` **Response Members** ### `success` *boolean* Whether the job was successfully deleted. Example Response ```json { "success": true } ``` ## Run Job (Notehub) Execute a [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `POST` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}/run` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `jobUID` - The globally-unique identifier of a batch job. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | developer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments ### `dry_run` *boolean (optional, default `false`)* When `true`, runs the job in dry-run mode without making actual changes. **Example** **Bash** ```bash curl -X POST -L 'https://api.notefile.net/v1/projects//jobs//run' -H 'Authorization: Bearer ' ``` **Response Members** ### `report_uid` *string* The globally-unique identifier of the job run. Use this to check the run's status with [Get Job Run](#get-job-run). Example Response ```json { "report_uid": "00000000-0000-0000-0000-000000000000" } ``` ## Get Job Runs (Notehub) List all runs for a specific [batch job](https://dev.blues.io/notehub/notehub-walkthrough.md#running-batch-jobs). | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}/runs` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `jobUID` - The globally-unique identifier of a batch job. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments ### `status` *string (optional)* Filter runs by status. ### `dry_run` *boolean (optional)* Filter runs by whether they were executed as a dry run. **Example** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//jobs//runs' -H 'Authorization: Bearer ' ``` **Response Members** ### `runs` *array of objects* An array of job run objects. Each object contains the following fields: ### `runs.report_uid` *string* The globally-unique identifier of the job run. ### `runs.job_uid` *string* The globally-unique identifier of the batch job. ### `runs.job_name` *string* The name of the batch job. ### `runs.status` *string* The current status of the job run. ### `runs.dry_run` *boolean* Whether the job run was executed in dry-run mode. ### `runs.submitted_by` *string* The email address of the user who submitted the job run. ### `runs.submitted` *UNIX Epoch time* The time the job run was submitted. ### `runs.started` *UNIX Epoch time* The time the job run started executing. ### `runs.updated` *UNIX Epoch time* The time the job run was last updated. ### `runs.cancel` *boolean* Whether a cancellation has been requested for this job run. Example Response ```json { "runs": [ { "report_uid": "00000000-0000-0000-0000-000000000000", "job_uid": "00000000-0000-0000-0000-000000000001", "job_name": "my-batch-job", "status": "completed", "dry_run": false, "submitted_by": "user@example.com", "submitted": 1700000000, "updated": 1700000060, "cancel": false } ] } ``` ## Get Job Run (Notehub) Get the result of a job execution. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `reportUID` - The globally-unique identifier of a job run. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments ### `view` *string (optional)* Controls the level of detail returned. `summary` returns metadata only; `detail` returns the full result payload. Defaults to `summary`. **Basic** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//jobs/runs/' -H 'Authorization: Bearer ' ``` **Response Members** ### `report_uid` *string* The globally-unique identifier of the job run. ### `job_uid` *string* The globally-unique identifier of the batch job. ### `job_name` *string* The name of the batch job. ### `status` *string* The current status of the job run. ### `dry_run` *boolean* Whether the job run was executed in dry-run mode. ### `submitted_by` *string* The email address of the user who submitted the job run. ### `submitted` *UNIX Epoch time* The time the job run was submitted. ### `started` *UNIX Epoch time* The time the job run started executing. ### `updated` *UNIX Epoch time* The time the job run was last updated. ### `completed` *UNIX Epoch time* The time the job run completed. ### `cancel` *boolean* Whether a cancellation has been requested for this job run. ### `results` *object* The results of the job run. Structure varies by job type. Example Response ```json { "report_uid": "00000000-0000-0000-0000-000000000000", "job_uid": "00000000-0000-0000-0000-000000000001", "job_name": "my-batch-job", "status": "completed", "dry_run": false, "submitted_by": "user@example.com", "submitted": 1700000000, "updated": 1700000060, "completed": 1700000060, "results": {} } ``` ## Cancel Job Run (Notehub) Cancel a running job execution. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP Method: | `POST` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}/cancel` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `reportUID` - The globally-unique identifier of a job run. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | developer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments None **Example** **Bash** ```bash curl -X POST -L 'https://api.notefile.net/v1/projects//jobs/runs//cancel' -H 'Authorization: Bearer ' ``` **Response Members** ### `successful` *boolean* Whether the cancellation request was successfully submitted. Example Response ```json { "successful": true } ``` ## Delete Job Run (Notehub) Delete the results of a job run. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP Method: | `DELETE` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. - `reportUID` - The globally-unique identifier of a job run. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | developer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | Arguments None **Example** **Bash** ```bash curl -X DELETE -L 'https://api.notefile.net/v1/projects//jobs/runs/' -H 'Authorization: Bearer ' ``` **Response Members** ### `success` *boolean* Whether the job run was successfully deleted. Example Response ```json { "success": true } ``` [Event API](https://dev.blues.io/api-reference/notehub-api/event-api.md "Event API") [Monitor API](https://dev.blues.io/api-reference/notehub-api/monitor-api.md "Monitor API")