Jobs

ThreatConnect can integrate with many third-party applications and services via TC Exchange™ Apps. Once installed, an App leverages a corresponding Job to perform the actions that the App supports.

Endpoint: /api/v3/jobs

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields that may be included in responses returned from the /v3/jobs endpoint, which is a read-only endpoint:

OPTIONS /v3/jobs?show=readonly

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/jobs endpoint:

OPTIONS /v3/jobs/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/jobs endpoint:

OPTIONS /v3/jobs/tql

Hint

See the “Retrieve a Specific Job” section for example use cases of the tql query parameter.

Schemas

Response Body

The default response returned from a successful GET request to the /v3/jobs endpoint includes one or more objects with the following fields:

id: <Integer> The Job’s ID number.
name: <String> The Job’s name.
displayName: <String> The name of the App to which the Job corresponds. This is the name of the App as it is shown in TC Exchange.
programName: <String> The name of the App to which the Job corresponds.
programVersion: <String> The version of the App to which the Job corresponds.
active: <Boolean> Specifies whether the Job is active.

Example

{
    "id": <int>,
    "name": "<string>",
    "displayName": "<string>",
    "programName": "<string>",
    "programVersion": "<string>",
    "active": <boolean>
}

Retrieve Jobs

Retrieve All Jobs

Send the following request to retrieve data for all Jobs in your Organization:

Request

GET /v3/jobs

Response

{
    "data": [
        {
            "id": 10,
            "name": "QRadar",
            "displayName": "QRadar Integration",
            "programName": "TC - QRadar Extract v2.2",
            "programVersion": "2.2.22",
            "active": true
        },
        {
            "id": 9,
            "name": "Import from MISP",
            "displayName": "MISP-Import",
            "programName": "TC - MISP Import v1.0",
            "programVersion": "1.0.34",
            "active": false
        },
        {...}
    ],
    "status": "Success"
}

Hint

To include details about a Job’s most recent execution in the API response, append ?fields=lastExecution to the end of the request URL.

Retrieve a Specific Job

The following requests demonstrate how to use TQL to retrieve data for a specific Job.

Filter by ID Number

In the following example, the API request will retrieve data only for the Job whose ID number is 12345:

Request (Decoded URL)

GET /v3/jobs?tql=id = 12345

Request (Encoded URL)

GET /v3/jobs?tql=id%20%3D%2012345

Filter by Name

In the following example, the API request will retrieve data only for the Job whose name is Test Job:

Request (Decoded URL)

GET /v3/jobs?tql=name = "Test Job"

Request (Encoded URL)

GET /v3/jobs?tql=name%20%3D%20%22Test%20Job%22