Event API
Tip
Direct interaction with the API is intended for advanced use cases. Try starting with the pre-built snippets.
About the API
The Sumatra Event API is a REST interface that allows application developers to send JSON events to Sumatra, to be enriched in real-time by topologies defined in Scowl.
Authentication
Sumatra uses API keys, via the x-api-key
header, to allow access to endpoints. These keys should be kept secret.
curl https://api.sumatra.ai/event \
-H 'x-api-key: SUMATRA_API_KEY'
Note
Replace SUMATRA_API_KEY
with your private API key. Find it by logging into your account and navigating to Events -> Setup.
Request
A POST
action to the event
endpoint takes a raw JSON event, processes it with the
corresponding event processor, and returns the requested features, rules, and/or decisions.
Query Parameters
The decisions
, features
, and rules
query parameters can be used to specify which data to return in the response.
Parameter | Required | Description |
---|---|---|
decisions | no | If set, the response will include decisions |
rules | no | If set, the response will include all fired rules |
features | no | If set, the response will include all enriched features |
Example
POST https://api.sumatra.ai/event?decisions&rules
Request Format
The body of this request should be a JSON structure, with one required field,_type
, which should be the name of an event type in the Live Topology.
JSON Path | Required | Type | Description |
---|---|---|---|
$._type |
yes | string | The event type used to route this input to the correct event processor |
Example
{
"_type": "signup",
"ip": "125.23.23.2",
"email": "james.t.smith@gmail.com"
}
Response
The JSON response payload contains required fields, along with a few additional fields that may be present, depending on which query parameters were set in the request.
JSON Path | Required | Type | Description |
---|---|---|---|
$.event_id |
yes | string | The server generated identifier for this event |
$.event_time |
yes | string | The server-side timestamp in UTC |
$.features |
no | map | Enriched features |
$.rules |
no | array | Rules fired for this event |
$.decisions |
no | map | Decisions for this event |
$.errors |
no | map | Feature resolution errors |
Example
{
"event_id": "693c56d9-22da-11eb-a5db-be0c6c9896a8",
"event_time": "2022-08-01T12:34:56.123Z",
"decisions": {
"verdict": "Block"
},
"errors": {
"ip": "required input missing"
},
"features": {
"email": "james.t.smith@gmail.com",
"high_velocity_ip": false,
"ip": null,
"ipc_block": null,
"is_duplicate_signup": true,
"normalized_email": "jamestsmith@gmail.com",
"num_logins_per_ip": 0,
"num_per_ip": 1,
"num_per_ip_network": 1,
"num_per_normalized_email": 5,
"verdict": "Block"
},
"rules": [
{
"name": "is_duplicate_signup",
"reason": "Duplicate email address.",
"rulings": {
"verdict": "Block"
}
}
]
}
Resolved Features
If the features
query string is present in the request URL, the features
field of the
response will contain a map of feature names to enriched features.
Example
"features": {
"email": "james.t.smith@gmail.com",
"high_velocity_ip": false,
"ip": null,
"ipc_block": null,
"is_duplicate_signup": true,
"normalized_email": "jamestsmith @gmail.com",
"num_logins_per_ip": 0,
"num_per_ip": 1,
"num_per_ip_network": 1,
"num_per_normalized_email": 7,
"verdict": "Block"
}
Triggered Rules
If the rules
query string is present in the request URL, the rules
field will contain an array of rules that were fired. Each rule will have a name, reason, and a map of rulings indicating which decisions this rule impacted and how.
Example
"rules": [
{
"name": "is_duplicate_signup",
"reason": "Duplicate email address.",
"rulings": {
"verdict": "Block"
}
}
]
Decisions
If the decisions
query string is present in the request URL, the decisions
field will contain a map of decision keys to decision values.
Example
"decisions": {
"verdict": "Block"
}
Resolution Errors
The errors
field will contain a map of feature names to error messages for errors encountered during resolution of features or feature dependencies. The errors field will be omitted if there are no errors.
Example
"errors": {
"ip": "required input missing"
}
HTTP Errors
The Sumatra Event API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
500 | Internal Server Error. We had a problem with our server. Try again later. |
503 | Service Unavailable. We're temporarily offline for maintenance. Please try again later. |