API Reference

Jobs Overview

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.
{
    "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:

GET /v3/jobs

{
    "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:

GET /v3/jobs?tql=id = 12345

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:

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

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

TC Exchange™ is a trademark of ThreatConnect, Inc.