Create

This method allows you to initiate and execute a new job against an environment, node group or node, or kick off a new node scan for a given node id. You should use the Nodes, Node groups or Environments Index methods to get the node, node group or environment id respectively to be used in the type_id field.

Method URL
POST /api/v1/jobs.json?type=environment&type_id=123
POST /api/v1/jobs.json?type=node&type_id=123
POST /api/v1/jobs.json?type=node_group&type_id=123
POST /api/v1/jobs.json?type=node_scan&type_id=123

Example Response

Code Status
201 Created

Example Response JSON

{
    "job_id": 123
}

Index

This method returns a list of jobs for the organization.

Method URL
GET /api/v1/jobs.json
GET /api/v1/jobs.json?page=1&per_page=2

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 256,
        "organisation_id": 33,
        "source_id": 22,
        "source_name": "",
        "source_type": 11,
        "status": 2,
        "url": "/api/v1/jobs/256.json"
    },
    {
        "id": 258,
        "organisation_id": 33,
        "source_id": 23,
        "source_name": "",
        "source_type": 11,
        "status": 2,
        "url": "/api/v1/jobs/258.json"
    }
]

Show

This method returns details of the job specified by the job ID in the URL.

Method URL
GET /api/v1/jobs/[job_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
    "created_at": "2012-10-30T16:16:52-07:00",
    "created_by": 178,
    "id": 294,
    "organisation_id": 185,
    "scheduled_job_id": null,
    "source_id": 1130,
    "source_name": "sandbox",
    "source_type": 2,
    "status": 2,
    "updated_at": "2012-10-30T16:16:57-07:00",
    "updated_by": 178,
    "upload_node_id": 251
}

A job’s status can be one of the following values:

Code Status Description
0 Pending A job is yet to be picked up for execution
1 Processing A job has been started and is currently being processed
2 Success A job has finished running and all tests passed
3 Cancelled A job is no longer running as it was cancelled early
-1 Failure A job has finished running and not all tests passed

A job’s source_type shows which type of object a job is based on. The source_type field can be one of the following values:

ID Type Description
1 Step The job was kicked off to run the single UpGuard test step given by source_id
2 Script The job was kicked off to run the script given by source_id
3 Policy The job was kicked off to run the policy given by source_id
4 Node The job was kicked off to run all policy versions assigned to the node given by source_id
5 Environment The job was kicked off to run all policy versions assigned to all nodes in the environment given by source_id
6 Policy Version The job was kicked off to run the policy version with id given by source_id
7 Node Group The job was kicked off to run all policy versions assigned to the node group given by source_id
11 Node Scan The job was kicked off to run a node scan on the node given by source_id
12 Environment Scan The job was kicked off to run a node scan across all nodes in the environment given by source_id

Tasks

This methods allows you to list tasks under a given job. An optional ‘status’ parameter can be supplied to filter for tasks with a given status.

Method URL
GET /api/v1/jobs/[job_id]/tasks.json
GET /api/v1/jobs/[job_id]/tasks.json?status=success
GET /api/v1/jobs/[job_id]/tasks.json?status=error,exception,timeout

Example Response

Code Status
200 OK

A task’s status can be one of the following values:

Code Status Description
0 Pending The task has been created and is yet to be picked up for processing.
1 Processing The task is currently being executed.
2 Success The task has completed with a successful result.
3 Assigned The task has been assigned to a specific agent in a multi-agent setup, but is yet to be picked up for processing.
9 Failure The task has completed with an unsuccessful result.
10 Offline The task tried to run, but the target node was offline.
20 Cancelled The task was cancelled before it finished executing.
55 Timeout The task took too long to execute and hit a timeout before it could complete.
88 Error The task failed to complete in either a success or failure state due to either a user error, a lack of information or other known way a test cannot definitively say if a test is true or false.
99 Exception Similar to the Error status, but usually not one of the common types of errors that can occur.
Tags: jobs