Skip to content

Message Center

The Message Center service collection provides operations for managing support cases and their associated activities and attachments. Retrieve aggregate case analytics, query and manage case activities, upload and download attachments, create new cases, and search for cases by filter criteria.

LanguageLast Update
Pythonv1.4.6
PowerShellv2.2.9
Gov0.20.0
TypeScriptv0.6.0
Rustv0.7.0
Rubyv1.2.0
OperationDescription
AggregateCases
aggregate_cases
Retrieve aggregate case values based on the matched filter
GetCaseActivityByIds
get_case_activity
Retrieve activities for given id’s
CaseAddActivity
add_case_activity
Add an activity to case. Only activities of type comment are allowed via API
CaseDownloadAttachment
download_case_attachment
retrieves an attachment for the case, given the attachment id
CaseAddAttachment
add_case_attachment
Upload an attachment for the case.
CreateCaseV2
create_case_v2
create a new case
GetCaseEntitiesByIDs
get_cases
Retrieve message center cases
QueryActivityByCaseID
query_activities
Retrieve activities id’s for a case
QueryCasesIdsByFilter
query_cases
Retrieve case id’s that match the provided filter criteria

Retrieve aggregate case values based on the matched filter

POST /message-center/aggregates/cases/GET/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 aggregate_cases
NameTypeData typeDescription
bodybodylist of dictionariesFull body payload in JSON format.
date_rangesbodylist of dictionariesApplies to date_range aggregations. Example: [{“from”: “2016-05-28T09:00:31Z”, “to”: “2016-05-30T09:00:31Z”}, {“from”: “2016-06-01T09:00:31Z”, “to”: “2016-06-10T09:00:31Z”}]
fieldbodystringThe field on which to compute the aggregation.
filterbodystringFQL syntax formatted string to use to filter the results.
intervalbodystringTime interval for date histogram aggregations. Valid values include: year, month, week, day, hour, minute.
min_doc_countbodyintegerOnly return buckets if values are greater than or equal to the value here.
missingbodystringMissing is the value to be used when the aggregation field is missing from the object. In other words, the missing parameter defines how documents that are missing a value should be treated. By default they will be ignored, but it is also possible to treat them as if they had a value.
namebodystringName of the aggregate query, as chosen by the user. Used to identify the results returned to you.
qbodystringFull text search across all metadata fields.
rangesbodylist of dictionariesApplies to range aggregations. Ranges values will depend on field. For example, if max_severity is used, ranges might look like: [{“From”: 0, “To”: 70}, {“From”: 70, “To”: 100}]
sizebodyintegerThe max number of term buckets to be returned.
sub_aggregatesbodylist of dictionariesA nested aggregation, such as: [{“name”: “max_first_behavior”, “type”: “max”, “field”: “first_behavior”}]. There is a maximum of 3 nested aggregations per request.
sortbodystringFQL syntax string to sort bucket results. _count - sort by document count. _term - sort by the string value alphabetically. Supports asc and desc using \| format. Example: _count\|desc
time_zonebodystringTime zone for bucket results.
typebodystringType of aggregation. Valid values include: date_histogram - Aggregates counts on a specified time interval. Requires use of “interval” field. date_range - Aggregates counts on custom defined date range buckets. terms - Buckets detections by the value of a specified field. range - Buckets detections by specified (numeric) ranges of a specified field. cardinality - Returns the count of distinct values in a specified field. max - Returns the maximum value of a specified field. min - Returns the minimum value of a specified field. avg - Returns the average value of the specified field. sum - Returns the total sum of all values for the specified field. percentiles - Returns the following percentiles for the specified field: 1, 5, 25, 50, 75, 95, 99.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
date_ranges = [
{
"from": "string",
"to": "string"
}
]
ranges = [
{
"From": 0,
"To": 0
}
]
response = falcon.aggregate_cases(date_ranges=date_ranges,
field="string",
filter="string",
interval="string",
min_doc_count=integer,
missing="string",
name="string",
q="string",
ranges=ranges,
size=integer,
sort="string",
sub_aggregates=["string"],
time_zone="string",
type="string")
print(response)

Retrieve activities for given id’s

POST /message-center/entities/case-activities/GET/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 get_case_activity
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
idsbodystring or list of stringsOne or more Case IDs.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.get_case_activity(ids=id_list)
print(response)

Add an activity to case. Only activities of type comment are allowed via API

POST /message-center/entities/case-activity/v1
Scope Message Center: WRITE Consumes · Produces application/json
PEP 8 add_case_activity
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
case_idbodystringCase ID to attach the activity to.
contentbodystringCase activity content. Used for the body key within the BODY payload.
typebodystringCase activity type.
user_uuidbodystringUUID of the user attached to the case activity.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.add_case_activity(content="string",
case_id="string",
type="string",
user_uuid="string")
print(response)

retrieves an attachment for the case, given the attachment id

GET /message-center/entities/case-attachment/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 download_case_attachment
NameTypeData typeDescription
idquerystringAttachment ID to retrieve.
parametersquerydictionaryFull query string parameters payload in JSON format.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.download_case_attachment(ids=id_list)
print(response)

Upload an attachment for the case.

POST /message-center/entities/case-attachment/v1
Scope Message Center: WRITE Consumes · Produces multipart/form-data application/json
PEP 8 add_case_attachment
NameTypeData typeDescription
case_idformDatastringCase ID to update.
dataformDatafileContent of the attachment in binary format. Max file size is 15 MB. Filename must start with a-zA-Z0-9_- and has a maximum of 255 characters. Allowed characters in file name are a-zA-Z0-9-_.. Accepted file formats: Images: .bmp, .jpg, .jpeg, .gif, .png. Adobe PDF: .pdf. Office documents: .doc, .docx, .ppt, .pptx, .xls, .xlsx. Text files: .csv, .txt.
file_data or sample or upfileformDatafileContent of the attachment in binary format. Max file size is 15 MB. sample and upfile are also accepted as this parameter. Filename must start with a-zA-Z0-9_- and has a maximum of 255 characters. Allowed characters in file name are a-zA-Z0-9-_.. Accepted file formats: Images: .bmp, .jpg, .jpeg, .gif, .png. Adobe PDF: .pdf. Office documents: .doc, .docx, .ppt, .pptx, .xls, .xlsx. Text files: .csv, .txt.
parametersquerydictionaryFull query string parameters payload in JSON format.
user_uuidformDatastringUUID of the user providing the attachment.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.add_case_attachment(case_id="string",
file_data="string",
file_name="string",
user_uuid="string")
print(response)

create a new case

POST /message-center/entities/case/v2
Scope Message Center: WRITE Consumes · Produces application/json
PEP 8 create_case_v2
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
contentbodystringCase content. Used for the body key within the BODY payload.
detectionsbodylist of dictionariesList of detections to attach to the case. Dictionary format: {“id”: “string”, “url”: “string”}
incidentsbodylist of dictionariesList of incidents to attach to the case. Dictionary format: {“id”: “string”, “url”: “string”}
titlebodystringCase title.
typebodystringCase type.
user_uuidbodystringUUID of the user attached to the case.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
detections = [
{
"id": "string",
"product": "string",
"url": "string"
}
]
response = falcon.create_case_v2(content="string",
detections=detections,
incidents=id_list,
title="string",
type="string",
user_uuid="string")
print(response)

Retrieve message center cases

POST /message-center/entities/cases/GET/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 get_cases
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
idsbodystring or list of stringsOne or more Case IDs.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
id_list = 'ID1,ID2,ID3' # Can also pass a list here: ['ID1', 'ID2', 'ID3']
response = falcon.get_cases(ids=id_list)
print(response)

Retrieve activities id’s for a case

GET /message-center/queries/case-activities/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 query_activities
NameTypeData typeDescription
case_idquerystringCase ID to search for activities.
filterquerystringThe filter expression that should be used to limit the results. FQL Syntax.
limitqueryintegerMaximum number of records to return. (Max: 500)
offsetqueryintegerStarting index of overall result set from which to return ids.
sortquerystringThe property to sort by. (Ex: case.created_time.desc) Available sort fields: case.created_time, case.id, case.last_modified_time, case.status, case.type.
parametersquerydictionaryFull query string parameters payload in JSON format.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_activities(case_id="string",
filter="string",
limit=integer,
offset=integer,
sort="string")
print(response)

Retrieve case id’s that match the provided filter criteria

GET /message-center/queries/cases/v1
Scope Message Center: READ Consumes · Produces application/json
PEP 8 query_cases
NameTypeData typeDescription
filterquerystringThe filter expression that should be used to limit the results. FQL Syntax.
limitqueryintegerMaximum number of records to return. (Max: 500)
offsetquerystringStarting index of overall result set from which to return ids.
sortquerystringThe property to sort by. (Ex: case.created_time.desc) Available sort fields: case.created_time, case.id, case.last_modified_time, case.status, case.type.
parametersquerydictionaryFull query string parameters payload in JSON format.
from falconpy import MessageCenter
falcon = MessageCenter(client_id=CLIENT_ID,
client_secret=CLIENT_SECRET
)
response = falcon.query_cases(filter="string",
limit=integer,
offset=integer,
sort="string")
print(response)