Event API

The Sumatra Event API is use for both tracking events and fetching feature values. This design provides the flexibility to: track only, query only, or do both in a single synchronous call.

Introduction

The API accepts JSON events sent from your application and, if requested, returns feature values computed by the topology for the specified event type.

Here is an example how you would call the API with curl:

curl --request POST \
  --url 'https://api.sumatra.ai/event?features' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ak_8VZjYKnbF3ZAPCiWpQLfjHn4B' \
  --data '{
    "_type": "add_to_cart",
    "user_id": 123,
    "product_id": 45678
}'

Tip

Client-side and Server-side SDKs are available for most common frameworks, providing a simpler, more reliable integration than calling the API directly.

Authentication

Sumatra uses API keys, via the x-api-key header, to allow access to endpoints. For client-side integration, the key will be visible. For server-side, the key should be kept secret.

curl https://api.sumatra.ai/event \
   -H 'x-api-key: SUMATRA_API_KEY'

Note

Replace SUMATRA_API_KEY with your workspace API key. As a workspace owner, you can find your key by logging into the UI and navigating to Settings.

Request

A POST action to the event endpoint takes a raw JSON event, processes it with the corresponding topology, 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.