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