Accessing the API
Base URL
https://dashboard.signalsciences.net/api/v0
Examples
For examples on how to authenticate against and use the API, see Using our API.
Auth
Log into the API
post /auth
Request
Form Parameters
Responses
HTTP 200
Token to be used in subsequent requests for authentication
Response Example
{
"token": "a3024fcf-0c8a-43d8-b70b-ed537fe50650"
}
HTTP 401
Login failed
Log out the session
get /auth/logout
Request
No request parameters.
Responses
HTTP 302
Redirects to the login page
Corps
List corps
get /corps
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"data": [
{
"name": "testcorp",
"displayName": "Test Corporation",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
]
}
Get corp by name
get /corps/{corpName}
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"name": "testcorp",
"displayName": "Test Corporation",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
Update corp by name
patch /corps/{corpName}
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Body (application/json)
Display name of the corp
Small icon URI
Dashboard session timeout (seconds)
Request Example
{
"displayName": "Test Corporation1"
}
Responses
HTTP 200
Successful update
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"name": "testcorp",
"displayName": "Test Corporation1",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
HTTP 400
Failed due to data input
Error message
Response Example
{"message":"Invalid displayName - must be between 3 and 100 characters."}
Get corp overview report
get /corps/{corpName}/reports/attacks
Request
Query Parameters
Pretty print the json output
Number of days ago to begin the data window. Takes the format "-Nd" where N is the number of days (maximum 30).
Number of days ago to end the data window. Takes the format "-Nd" where N is the number of days (maximum 30).
Responses
HTTP 200
Identifying name of the site
Display name of the site
Total number of requests
Number of malicious requests
Number of malicious requests blocked
Number of malicious requests that would have been blocked in blocking mode
Number of IPs that triggered blocking events due to malicious signals
Attack tag name
Number of instances of this attack tag
Total attack tags seen (note - requests can have multiple tags)
Two-letter ISO country code (note - empty for "Unknown", "private" for "Private Network"
Descriptive country name
Number of requests originating from this country
Total attack requests
Response Example
{
"data": [
{
"name":"www.example.com",
"displayName":"Example Site",
"totalCount":49285068291,
"blockedCount":29184,
"flaggedCount":0,
"attackCount":43129,
"previousPeriodAttackCount": 40218,
"previousPeriodBlockedCount": 39190,
"flaggedIPCount":15,
"topAttackTypes":[
{
"tagName":"Attack Tooling",
"tagCount":32551,
"totalCount":49712
},
{
"tagName":"CMDEXE",
"tagCount":5065,
"totalCount":49712
},
{
"tagName":"XSS",
"tagCount":4383,
"totalCount":49712
}
],
"topAttackSources":[
{
"countryCode":"CA",
"countryName":"Canada",
"requestCount":12414,
"totalCount":43129
},
{
"countryCode":"private",
"countryName":"Private Network",
"requestCount":6204,
"totalCount":43129
},
{
"countryCode":"",
"countryName":"",
"requestCount":5322,
"totalCount":43129
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid parameter - from"}
List corp activity events
get /corps/{corpName}/activity
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
The sort order
The id of the last object in the set
The id of the last object in the set
The number of entries to be returned per page
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
Pretty print the json output
Filter on events
Filter on event type
Responses
HTTP 200
Total number of matching documents
Unique ID of the activity event
Event type
Data used to format the message
Message of the event
Created RFC3339 date time
Response Example
{
"totalCount": 5,
"next": {
"uri": "/api/v0/corps/testcorp/activity?limit=1&page=2"
},
"data": [
{
"id": "random-uuid-string",
"eventType": "userMultiFactorAuthEnabled",
"msgData": {},
"message": "User (user@example.com) enabled 2FA",
"attachments": [],
"created": "2018-04-12T01:00:33Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid parameter - from"}
List users in corp
get /corps/{corpName}/users
Request
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"data": [
{
"name": "Test User",
"email": "user@example.com",
"announcements": {
"uri": "/api/v0/user/announcements"
},
"defaultDashboards": {
"uri": "/api/v0/user/defaultDashboards"
},
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00",
}
]
}
Get corp user by email
get /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "Test User",
"email": "user@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
Update corp user by email
patch /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "staging"
}
}, {
"site": {
"name": "production"
}
}]
}
}
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "",
"email": "user@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
Delete user from corp
delete /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Invite user to corp
post /corps/{corpName}/users/{userEmail}/invite
Request
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "staging"
}
}, {
"site": {
"name": "production"
}
}]
}
}
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "",
"email": "example@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List rules in corp
get /corps/{corpName}/rules
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Total count of Corp Rules
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": [
{
"id": "5e191909c931498586c6f537",
"siteNames": [],
"type": "request",
"corpScope": "global",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.1/8"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "foo",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
]
}
}
Create corp rule
post /corps/{corpName}/rules
Request
Query Parameters
Pretty print the json output
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"siteNames": [
"staging",
"production"
],
"type": "signal",
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.204"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.123"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"enabled": true,
"reason": "test",
"signal": "SQLI",
"expiration": "",
"corpScope": "specificSites"
}
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.31"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.63"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Get corp rule by id
get /corps/{corpName}/rules/{id}
Request
URI Parameters
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": {
"id": "5e191909c931498586c6f537",
"siteNames": [],
"type": "request",
"corpScope": "global",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.1/8"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "foo",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
}
}
Update corp rule
put /corps/{corpName}/rules/{id}
Request
URI Parameters
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"id": "5e1914acf13d663e6d0178ea",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.76"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.156"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.101"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.86"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Delete rule from corp
delete /corps/{corpName}/rules/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Get all lists
get /corps/{corpName}/lists
Request
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": [
{
"id": "corp.known-attackers",
"name": "Known Attackers",
"type": "ip",
"description": "Malicious IPs we're tracking",
"entries": [
"198.51.100.165",
"233.252.0.215",
"192.0.2.186"
],
"createdBy": "user@example.com",
"created": "2018-08-06T18:57:55Z",
"updated": "2018-08-13T15:26:01Z"
},
{
"id": "corp.ofac-countries",
"name": "OFAC Countries",
"type": "country",
"description": "Countries on the OFAC list",
"entries": [
"MM",
"CI",
"CU",
"IR",
"KP",
"SY"
],
"createdBy": "user@example.com",
"created": "2018-08-03T20:50:54Z",
"updated": "2018-08-03T20:50:59Z"
}
]
}
Create list
post /corps/{corpName}/lists
Request
Body (application/json)
Descriptive list name
List types (string, ip, country, wildcard, signal)
Optional list description
List entries
Request Example
{
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 400
Error message
Response Example
{"message":"List cannot be deleted because a rule uses it"}
Get list by id
get /corps/{corpName}/lists/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 404
Error message
Response Example
{"message":"id not found"}
Update list by id
patch /corps/{corpName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List additions
List deletions
Request Example
{
"entries": {
"additions": [
"192.0.2.19"
],
"deletions": [
"192.0.2.186",
"233.252.0.174"
]
}
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"198.51.100.138",
"192.0.2.19"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"id not found"}
Replace list by id
put /corps/{corpName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List entries
Request Example
{
"description": "Some IPs we're still putting in a list",
"entries": [
"192.0.2.186",
"233.252.0.174",
"198.51.100.193"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"192.0.2.186",
"233.252.0.174",
"198.51.100.193"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete list
delete /corps/{corpName}/lists/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List corp integrations
get /corps/{corpName}/integrations
Request
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "556a8abb3dfaa4ff28000002",
"name": "Slack message",
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"fields": null,
"events": [
"corpUpdated"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
]
}
Create corp integration
post /corps/{corpName}/integrations
Request
Body (application/json)
Integration URL
Corp integration types (mailingList, slack, microsoftTeams). Site integration types (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Request Example
{
"url":"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"type":"slack",
"events": [
"corpUpdated"
],
"note": ""
}
Responses
HTTP 200
Unique ID of the integration
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Email address of the user that created the integration
ID of the user that created the integration
Integration note
Created RFC3339 date time
Response Example
{
"ID": "5e2f5d17f13d66152d396956",
"Type": "slack",
"URL": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"ExtraFields": null,
"Events": [
"corpUpdated"
],
"Active": true,
"CreatedBy": "user@example.com",
"CreatedByID": "5e222f75f13d666c9eaec7d9",
"Note": "",
"Created": "2020-01-27T21:58:47.608359Z",
"LastStatusCode": 0
}
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
Get corp integration by id
get /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "556a8abb3dfaa4ff28000002",
"name": "Slack message",
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"fields": null,
"events": [
"corpUpdated"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Update corp integration by id
patch /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Request Example
{
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": ["listCreated", "corpUpdated"]
}
Responses
HTTP 204
Successful update
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Delete corp integration
delete /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Test corp integration by id
post /corps/{corpName}/integrations/{id}/test
Request
URI Parameters
Responses
HTTP 200
Test successful
HTTP 500
Test failed
List CloudWAF instances
get /corps/{corpName}/cloudwafInstances
Request
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
Create CloudWAF instance
post /corps/{corpName}/cloudwafInstances
Request
Body (application/json)
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.(Supported region: "us-east-1", "us-west-1", "af-south-1", "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-west-1", "eu-west-2", "eu-west-3", "sa-east-1", "us-east-2", "us-west-2").
TLS minimum version. Versions Available: "1.0", "1.2".
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers. (default: false)
List of domain or request URIs, up to 100 entries.
Request Example
{
"name": "test",
"description": "test",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"workspaceConfigs": [
{
"siteName": "www.example.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id"],
"domains": ["www.example.com"],
"origin": "https://origin.example.com",
"passHostHeader": false,
"connectionPooling": true,
"trustProxyHeaders": false
}
]
}
]
}
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.example.com"}
Get CloudWAF instance by id
get /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
Response Example
{
"id": "id1",
"name": "website",
"description": "a website",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"workspaceConfigs": [
{
"siteName": "www.example.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id2"],
"domains": ["www.example.com"],
"origin": "https://www.origin.example.com",
"passHostHeader": false,
"id": "id3",
"connectionPooling": true,
"trustProxyHeaders": false
}
]
}
],
"deployment": {
"status": "done",
"message": "",
"egressIPs": [
{
"ip": "233.252.0.152",
"status": "reachable",
"updatedAt": "2021-04-08T17:10:58Z"
}
],
"dnsEntry": "example.signalsciencescloud.net"
},
"useUploadedCertificates": true,
"createdBy": "user@example.com",
"created": "2021-04-08T15:50:46Z"
}
Update CloudWAF instance
put /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Body (application/json)
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.(Supported region: "us-east-1", "us-west-1", "af-south-1", "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-west-1", "eu-west-2", "eu-west-3", "sa-east-1", "us-east-2", "us-west-2").
TLS minimum version. Versions Available: "1.0", "1.2".
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers. (default: false)
List of domain or request URIs, up to 100 entries.
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.example.com"}
Delete CloudWAF instance
delete /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Responses
HTTP 204
delete successful
HTTP 400
Response Example
{"message":"cannot delete with pending instance"}
Restart CloudWAF instance
post /corps/{corpName}/cloudwafInstances/{deployment_id}/restart
Request
URI Parameters
Responses
HTTP 204
restart successful
List CloudWAF certificates
get /corps/{corpName}/cloudwafCerts
Request
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Upload CloudWAF certificate
post /corps/{corpName}/cloudwafCerts
Request
Body (application/json)
Friendly name to identify a CloudWAF certificate
List of domains - deprecated
Private key of the certificate in PEM format - must be unencrypted
Body of the certificate in PEM format
Certificate chain in PEM format
Request Example
{
"name": "someCertificate",
"domains": [
"example.com"
],
"privateKey": "-----BEGIN PRIVATE KEY-----\n someCertificate private key \n-----END PRIVATE KEY-----\n",
"certificateBody": "-----BEGIN CERTIFICATE-----\n someCertificate certificate body \n-----END CERTIFICATE-----\n",
"certificateChain": ""
}
Responses
HTTP 201
CloudWAF certificate unique identifier
Response Example
{"id": "someCertificate-id" }
HTTP 400
Response Example
{"message":"example.net is not associated with the specified TLS certificate.: unexpected domain, got = example.net"}
Get CloudWAF certificate by id
get /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Response Example
{
"id":"some-id",
"name":"website",
"domains":["example.com"],
"certificateBody":"-----BEGIN CERTIFICATE-----\n certificate body \n-----END CERTIFICATE-----",
"certificateChain":"",
"fingerprint": "",
"expiresAt":"2021-05-02T20:48:02Z",
"status":"active",
"createdBy":"user@example.com",
"created":"2021-02-01T22:05:23Z",
"updatedBy":"user@example.com",
"updatedAt":"2021-02-01T22:06:17Z"
}
Update CloudWAF certificate by id
put /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Body (application/json)
Friendly name to identify a CloudWAF certificate
Request Example
{
"name": "some name"
}
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Response Example
{
"id": "some-id",
"name": "some certificate",
"domains": [
"website"
],
"certificateBody": "-----BEGIN CERTIFICATE-----\n some certificate certificate body\n-----END CERTIFICATE-----\n",
"certificateChain": "-----BEGIN CERTIFICATE-----\n some certificate certificate chain\n-----END CERTIFICATE-----\n",
"fingerprint": "",
"expiresAt": "2022-01-28T20:32:47Z",
"status": "active",
"createdBy": "user@example.com",
"created": "2021-01-28T20:34:06.952625Z",
"updatedBy": "user@example.com",
"updatedAt": "2021-03-10T17:51:17.540049Z"}
HTTP 400
Response Example
{"message":"name cannot be empty"}
Delete CloudWAF certificate by id
delete /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
HTTP 400
Response Example
{"message":"certificate f179ae5fd6d8b5f742753e7019936d7e58e5c5bf used in deployments: cert is in use"}
Sites
List sites in corp
get /corps/{corpName}/sites
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Filter on site name or display name
The page of the results
The number of entries to be returned
Filter on agent mode
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Response Example
{
"data": [
{
"name": "www.example.com",
"displayName": "My Website",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 86400,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
]
}
Create site in corp
post /corps/{corpName}/sites
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Body (application/json)
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Request Example
{
'name": "www.example.com",
"displayName": "Example Website",
"agentLevel": "block",
"blockDurationSeconds": 259200,
"blockHTTPCode": 302,
"blockRedirectURL": "/blocked/"
}
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Response Example
{
"name": "www.example.com",
"displayName": "My Website1",
"agentLevel": "block",
"blockHTTPCode": 302,
"blockDurationSeconds": 259200,
"blockRedirectURL": "/blocked/",
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"tags": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/tags"
},
"rules": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rules"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
HTTP 400
Error message
Response Example
{"message":"Invalid block code - must be between 100 and 599"}
Get site by name
get /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Response Example
{
"name": "www.example.com",
"displayName": "My Website",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 86400,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"rateLimitedIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rateLimitedIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Update a site by name
patch /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Request Example
{
"displayName": "My Website1",
"agentLevel": "block",
"blockDurationSeconds": 259200
}
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Response Example
{
"name": "www.example.com",
"displayName": "My Website1",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 259200,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"rateLimitedIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rateLimitedIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"tags": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/tags"
},
"rules": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/advancedRules"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
HTTP 400
Error message
Response Example
{"message":"Invalid block code - must be between 100 and 599"}
Delete site
delete /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Delete successful
List site activity events
get /corps/{corpName}/sites/{siteName}/analytics/events
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
The sort order
The id of the last object in the set
The id of the last object in the set
The number of entries to be returned per page
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
Pretty print the json output
Filter on events
Filter on event type
Responses
HTTP 200
Total number of matching documents
Unique ID of the activity event
Event type
Data used to format the message
Message of the event
Created RFC3339 date time
Response Example
{
"totalCount": 5,
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events?limit=1&page=2"
},
"data": [
{
"id": "558cf75c3dfaa4b9c2000001",
"eventType": "blacklistIP",
"msgData": {"ip": "192.0.2.149"},
"message": "User (user@example.com) blacklisted \"192.0.2.149\"",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Create or Update Edge Deployment
put /corps/{corpName}/sites/{siteName}/edgeDeployment
This call initializes the Next-Gen WAF deployment in Compute@Edge and configures the site for Edge Deployment.
Request
Headers
Must be 'application/json'
Responses
HTTP 200
Initialization successful
Create or Update Edge Deployment Service
put /corps/{corpName}/sites/{siteName}/edgeDeployment/{fastlySID}
This call copies the backends from the Fastly service to the Edge Deployment and configures the Fastly service with an edge dictionary and dynamic VCL snippets. These configurations are needed to forward traffic to the WAF. Note that the changes to the Fastly service will be activated unless the `activateVersion` field is passed as `false`.
Request
URI Parameters
Fastly service ID
Headers
Fastly API key with write access to the Fastly service
Must be 'application/json'
Body (application/json)
Optional percent of requests that should be inspected by Next-Gen WAF
Optional flag that indicates whether the VCL version should be activated (true) or not activated (false)
Request Example
{
"percentEnabled": 0,
"activateVersion": true
}
Responses
HTTP 200
Service configuration successful
Detach Edge Deployment Service
delete /corps/{corpName}/sites/{siteName}/edgeDeployment/{fastlySID}
This call removes all backends from the Edge Deployment connected to the Fastly service and detaches the Fastly Service from the Edge Deployment. Note that requests will still forward the Edge Deployment until it is removed from the Fastly Service VCL.
Request
URI Parameters
Fastly service ID
Headers
Fastly API key with write access to the Fastly service
Must be 'application/json'
Responses
HTTP 200
Service detachment successful
Update Edge Deployment backends
put /corps/{corpName}/sites/{siteName}/edgeDeployment/{fastlySID}/backends
This call checks if any changes were made to the Fastly service's backends and updates the Edge Deployment if necessary. Note that the Fastly service must already be configured for Edge Deployment.
Request
Headers
Fastly API key with read access to the Fastly service
Must be 'application/json'
Responses
HTTP 200
Backend syncing successful
List site members
get /corps/{corpName}/sites/{siteName}/members
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"data": [
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Add members to site
post /corps/{corpName}/sites/{siteName}/members
Request
Query Parameters
Pretty print the json output
Body (application/json)
List of existing user email addresses
Request Example
{
"members: ["user@example.com"]
}
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"data": [
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid user"}
Get site member by email
get /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
},
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete from site members
delete /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Invite a site member
post /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}/invite
Request
Query Parameters
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "observer"
}
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List rules in site
get /corps/{corpName}/sites/{siteName}/rules
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Total count of Site Rules
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": [
{
"id": "5e191909c931498586c6f537",
"siteNames": [
"www.example.com"
],
"type": "request",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.100"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "test",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
]
}
}
Create site rule
post /corps/{corpName}/sites/{siteName}/rules
Request
Query Parameters
Pretty print the json output
Body (application/json)
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit. Can be set to ALL-REQUESTS to act upon all requests from a client.
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 86400)
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"type": "signal",
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.136"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.212"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"enabled": true,
"reason": "Example site rule",
"signal": "SQLI",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.136"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.212"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Example site rule",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:41:04Z"
}
Get site rule by id
get /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.137"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Example site rule",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:41:04Z"
}
Update site rule
put /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit. Can be set to ALL-REQUESTS to act upon all requests from a client.
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 86400)
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"id": "5e321810f13d660ea4cd8d0f",
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.177"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.177"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:45:21Z"
}
Delete rule from site
delete /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
List available rule templates
get /corps/{corpName}/sites/{siteName}/templates
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"data": [
{
"id": "LOGINATTEMPT",
"name": "LOGINATTEMPT",
"shortName": "Login Attempts",
"description": "Indicates a login attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/auth/*"
}
]
},
{
"id": "REGATTEMPT",
"name": "REGATTEMPT",
"shortName": "Registration Attempts",
"description": "Indicates a registration attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/register/*"
}
]
}
]
}
Get rule template by id
get /corps/{corpName}/sites/{siteName}/templates/{id}
Request
URI Parameters
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"id": "LOGINATTEMPT",
"name": "LOGINATTEMPT",
"shortName": "Login Attempts",
"description": "Indicates a login attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/auth/*"
}
]
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List configured templated rules
get /corps/{corpName}/sites/{siteName}/configuredtemplates
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"data": [
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
]
}
Get configured template rule by id
get /corps/{corpName}/sites/{siteName}/configuredtemplates/{id}
Request
URI Parameters
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Update site template rule by name
post /corps/{corpName}/sites/{siteName}/configuredtemplates/{id}
Request
URI Parameters
Body (application/json)
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
A flag to toggle this detection
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Request Example
{
"alertAdds": [
{
"action": "info",
"enabled": true,
"interval": 1,
"skipNotifications": false,
"longName": "LOGINATTEMPT-50-in-1",
"threshold": 50
}
],
"alertDeletes": [],
"alertUpdates": [],
"detectionAdds": [
{
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
]
}
],
"detectionDeletes": [],
"detectionUpdates": []
}
Responses
HTTP 200
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
Get all lists
get /corps/{corpName}/sites/{siteName}/lists
Request
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": [
{
"id": "site.known-attackers",
"name": "Known Attackers",
"type": "ip",
"description": "Malicious IPs we're tracking",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-06T18:57:55Z",
"updated": "2018-08-13T15:26:01Z"
},
{
"id": "site.ofac-countries",
"name": "OFAC Countries",
"type": "country",
"description": "Countries on the OFAC list",
"entries": [
"MM",
"CI",
"CU",
"IR",
"KP",
"SY"
],
"createdBy": "user@example.com",
"created": "2018-08-03T20:50:54Z",
"updated": "2018-08-03T20:50:59Z"
}
]
}
Create list
post /corps/{corpName}/sites/{siteName}/lists
Request
Body (application/json)
Descriptive list name
List types (string, ip, country, wildcard, signal)
Optional list description
List entries
Request Example
{
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 400
Error message
Response Example
{"message":"List cannot be deleted because a rule uses it"}
Get list by id
get /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Update list by id
patch /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List additions
List deletions
Request Example
{
"entries": {
"additions": [
"203.0.113.6"
],
"deletions": [
"203.0.113.247",
"192.0.2.137"
]
}
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"198.51.100.177",
"203.0.113.6"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Replace list by id
put /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List entries
Request Example
{
"description": "Some IPs we're still putting in a list",
"entries": [
"203.0.113.247",
"192.0.2.137",
"192.0.2.223"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"203.0.113.247",
"192.0.2.137",
"192.0.2.223"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete list
delete /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List alerts
get /corps/{corpName}/sites/{siteName}/alerts
Request
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
data: [
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
]
}
Create alert
post /corps/{corpName}/sites/{siteName}/alerts
Request
Body (application/json)
The name of the tag whose occurrences the alert is watching. Must match an existing tag
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Request Example
{
"tagName": "custom-tag",
"longName": "Example Alert",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged"
}
Responses
HTTP 201
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
Get alert
get /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
Update alert
patch /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Body (application/json)
The name of the tag whose occurrences the alert is watching. Must match an existing tag
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Request Example
{
"tagName": "custom-tag",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged"
}
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "random-uuid-string",
"siteId": "site-id-hex",
"tagName": "custom-tag",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged",
"created": "2015-02-14T21:17:16Z"
}
Delete alert
delete /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Search requests
get /corps/{corpName}/sites/{siteName}/requests
Request
Query Parameters
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
The number of entries to be returned per page
Pretty print the json output
Responses
HTTP 200
Total number of records matching the search
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"totalCount": 3,
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests?limit=1&page=1"
},
"data": [
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"responseMillis": 0,
"agentResponseCode": 200,
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get request by ID
get /corps/{corpName}/sites/{siteName}/requests/{requestID}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"agentResponseCode": 200,
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get request feed
get /corps/{corpName}/sites/{siteName}/feed/requests
Request
Query Parameters
Pretty print the json output
The POSIX Unix time to start. Has restrictions - see Extracting Your Data.