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.