homechevron_rightDocschevron_rightAPI Referencechevron_rightNotehub APIchevron_rightJobs API - Notehub API Reference

Jobs API

The Notehub jobs API provides RESTful methods that can be used to manage batch jobs.

A typical workflow is to create a job once from a job definition, then run it whenever you need to, and poll Get Job Run until the run completes. Each run produces a report that you can retrieve, cancel, or delete.

NameHTTP Request
Get JobsGET /v1/projects/{projectOrProductUID}/jobs
Create JobPOST /v1/projects/{projectOrProductUID}/jobs
Get JobGET /v1/projects/{projectOrProductUID}/jobs/{jobUID}
Delete JobDELETE /v1/projects/{projectOrProductUID}/jobs/{jobUID}
Run JobPOST /v1/projects/{projectOrProductUID}/jobs/{jobUID}/run
Get Job RunsGET /v1/projects/{projectOrProductUID}/jobs/{jobUID}/runs
Get Job RunGET /v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}
Cancel Job RunPOST /v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}/cancel
Delete Job RunDELETE /v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}

Get Jobs Notehub

List all batch jobs for a project.

HTTP Method:GET
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs
Path Parameters:
Minimum Notehub project-level role:viewer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments
None
curl -X GET
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs'
    -H 'Authorization: Bearer <access_token>'
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.

jobs.last_run_submitted

UNIX Epoch time

The time the job's most recent run was submitted. Omitted if the job has never been run.

jobs.last_run_completed

UNIX Epoch time

The time the job's most recent run completed. Omitted if the job has never been run or its most recent run is still in progress.

jobs.last_run_status

string

The status of the job's most recent run. See runs.status for the possible values. Omitted if the job has never been run.

Example Response
{
  "jobs": [
    {
      "job_uid": "00000000-0000-0000-0000-000000000000",
      "name": "My Batch Job",
      "created": 1750773741,
      "created_by": "user@example.com",
      "last_run_submitted": 1750774000,
      "last_run_completed": 1750774060,
      "last_run_status": "completed successfully"
    }
  ]
}

Create Job Notehub

Create a new batch job.

HTTP Method:POST
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs
Path Parameters:
Minimum Notehub project-level role:developer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments

name

string (required)

A name for the batch job.

This argument must be provided in the query string, so URL-encode any spaces or special characters (for example, ?name=My%20Batch%20Job).

body

object (required)

The job definition as a JSON object.

This object must be provided as the request's body.

curl -X POST
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs?name=<name>'
    -H 'Authorization: Bearer <access_token>'
    -H 'Content-Type: application/json'
    -d '<job_definition>'
Response Members

job_uid

string

The globally-unique identifier of the newly created batch job.

Example Response
{
  "job_uid": "00000000-0000-0000-0000-000000000000"
}

Get Job Notehub

Get details on a batch job.

HTTP Method:GET
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • jobUID - The globally-unique identifier of a batch job.
Minimum Notehub project-level role:viewer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments
None
curl -X GET
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/<jobUID>'
    -H 'Authorization: Bearer <access_token>'
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 email address of the user who created the job.

definition

object

The job definition provided when the job was created.

last_run_submitted

UNIX Epoch time

The time the job's most recent run was submitted. Omitted if the job has never been run.

last_run_completed

UNIX Epoch time

The time the job's most recent run completed. Omitted if the job has never been run or its most recent run is still in progress.

last_run_status

string

The status of the job's most recent run. See runs.status for the possible values. Omitted if the job has never been run.

Example Response
{
  "job_uid": "00000000-0000-0000-0000-000000000000",
  "name": "My Batch Job",
  "created": 1750773741,
  "created_by": "user@example.com",
  "definition": {
    "comment": "Generate a report on all devices",
    "select": {
      "all_devices": true
    },
    "report_options": {
      "device_info": true,
      "device_vars": true
    }
  },
  "last_run_submitted": 1750774000,
  "last_run_completed": 1750774060,
  "last_run_status": "completed successfully"
}

Delete Job Notehub

Delete a batch job. This also deletes all of the job's runs and their reports.

HTTP Method:DELETE
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • jobUID - The globally-unique identifier of a batch job.
Minimum Notehub project-level role:developer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments
None
curl -X DELETE
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/<jobUID>'
    -H 'Authorization: Bearer <access_token>'
Response Members

success

boolean

Whether the job was successfully deleted.

Example Response
{
  "success": true
}

Run Job Notehub

Execute a batch job.

The job runs asynchronously. This request returns as soon as the run is submitted, and you can poll Get Job Run to check its status and retrieve its results.

HTTP Method:POST
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}/run
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • jobUID - The globally-unique identifier of a batch job.
Minimum Notehub project-level role:developer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments

dry_run

boolean (optional, default false)

When true, runs the job in dry-run mode, which reports what the job would do without making any changes. We recommend a dry run before the first full run of any job that performs write operations.

This argument must be provided in the query string.

curl -X POST
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/<jobUID>/run'
    -H 'Authorization: Bearer <access_token>'
curl -X POST
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/<jobUID>/run?dry_run=true'
    -H 'Authorization: Bearer <access_token>'
Response Members

report_uid

string

The unique identifier of the job run, made up of the job's UID followed by a timestamp. Use this to check the run's status with Get Job Run.

Example Response
{
  "report_uid": "00000000-0000-0000-0000-000000000000-1750774000123"
}

Get Job Runs Notehub

List all runs for a specific batch job.

HTTP Method:GET
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/{jobUID}/runs
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • jobUID - The globally-unique identifier of a batch job.
Minimum Notehub project-level role:viewer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments

status

string (optional)

Return only runs whose status contains this text (case-insensitive). For example, status=completed matches both completed successfully and completed with errors. See runs.status for the possible values.

This argument must be provided in the query string.

dry_run

boolean (optional)

Filter runs by whether they were executed as a dry run.

This argument must be provided in the query string.

curl -X GET
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/<jobUID>/runs'
    -H 'Authorization: Bearer <access_token>'
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. A run starts as submitted and finishes as one of completed successfully, dry run completed successfully, completed with errors, or cancelled. While a run is in progress, Notehub may report per-device progress instead, such as dev:000000000000000 completed.

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.completed

UNIX Epoch time

The time the job run completed. Omitted while the run is still in progress.

runs.cancel

boolean

Whether a cancellation has been requested for this job run. Omitted when false.

Example Response
{
  "runs": [
    {
      "report_uid": "00000000-0000-0000-0000-000000000001-1700000000123",
      "job_uid": "00000000-0000-0000-0000-000000000001",
      "job_name": "My Batch Job",
      "status": "completed successfully",
      "dry_run": false,
      "submitted_by": "user@example.com",
      "submitted": 1700000000,
      "updated": 1700000060,
      "completed": 1700000060
    }
  ]
}

Get Job Run Notehub

Get the status and result of a job run.

HTTP Method:GET
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • reportUID - The globally-unique identifier of a job run.
Minimum Notehub project-level role:viewer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments

view

string (optional)

Controls the level of detail returned. summary (the default) returns the run's status and any errors. detail also includes the full report output, which can be large for jobs that select many devices.

This argument must be provided in the query string.

curl -X GET
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/runs/<reportUID>'
    -H 'Authorization: Bearer <access_token>'
curl -X GET
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/runs/<reportUID>?view=detail'
    -H 'Authorization: Bearer <access_token>'
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. See runs.status for the possible values.

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. Omitted while the run is still in progress.

cancel

boolean

Whether a cancellation has been requested for this job run. Omitted when false.

results

object

The results of the job run. Structure varies by job type.

Example Response
{
  "report_uid": "00000000-0000-0000-0000-000000000001-1700000000123",
  "job_uid": "00000000-0000-0000-0000-000000000001",
  "job_name": "My Batch Job",
  "status": "completed successfully",
  "dry_run": false,
  "submitted_by": "user@example.com",
  "submitted": 1700000000,
  "updated": 1700000060,
  "completed": 1700000060,
  "results": {
    "comment": "Generate a report on all devices",
    "job": {
      "type": "reconciliation",
      "job_uid": "00000000-0000-0000-0000-000000000001",
      "job_name": "My Batch Job",
      "status": "completed successfully",
      "who_submitted": "user@example.com",
      "when_submitted": 1700000000,
      "when_updated": 1700000060,
      "when_completed": 1700000060
    },
    "status": {
      "device_count": 2
    }
  }
}

Cancel Job Run Notehub

Cancel a job run.

HTTP Method:POST
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}/cancel
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • reportUID - The globally-unique identifier of a job run.
Minimum Notehub project-level role:developer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments
None
curl -X POST
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/runs/<reportUID>/cancel'
    -H 'Authorization: Bearer <access_token>'
Response Members

successful

boolean

true if the run was cancelled, or false if it had already been cancelled.

Example Response
{
  "successful": true
}

Delete Job Run Notehub

Delete a job run and its report.

HTTP Method:DELETE
URL:https://api.notefile.net/v1/projects/{projectOrProductUID}/jobs/runs/{reportUID}
Path Parameters:
  • projectOrProductUID - The ProjectUID or ProductUID of a Notehub project.
  • reportUID - The globally-unique identifier of a job run.
Minimum Notehub project-level role:developer
Required HTTP Headers:Authorization: Bearer <token>, where the token is a valid authentication token.
Arguments
None
curl -X DELETE
    -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/jobs/runs/<reportUID>'
    -H 'Authorization: Bearer <access_token>'
Response Members
None: an empty object {} means success.
Event API Monitor API