Skip to content

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.