Skip to main content

API

You can send us events by a single POST request to https://inn.gs/e/$ingestKey. The request body must be your JSON-encoded event, and a maximum of 32KB. On success, the API returns a 201 status code.

Our ingestion API allows you to perform a single POST request to submit an event from your application code.

Requests

You can send us events by making a single HTTP POST request to https://inn.gs/e/$ingestKey, swapping $ingestKey for an ingest key from your dashboard.

The body must be your JSON-encoded event payload in the format described in our event documentation, and can currently be no larger than 32KB. If you need to increase your payload limit, contact us.

An example curl request:

curl -X POST 'https://inn.gs/e/some-test-key-name-goes-here-bjm8xj6nji0vzzu0l1k' \
-d '{"name": "test.event", "data": { "favorites": ["milk", "tea", "eggs"] } }'

Responses

The API server returns status codes to indicate the status of the request:

  • 201: The event was successfully ingested
  • 400: The request was malformed
  • 401: The ingest key was not found
  • 403: The event does not match the ingest key filter
  • 413: The event is greater than your limit (currently 32KB)

Authentication: ingest keys

Your keys for authenticating with the event ingestion API are visible within the dashboard (in Events → Ingestion). By default, each workspace has a single ingestion key which can send any event from any IP.

You can create new ingest keys at any time, and you can have up to 100 ingest keys in a workspace.

Filtering: allowlists and denylists

When creating ingest keys you can add an optional filter. A filter is either an allowlist or a denylist:

Allowlist

allowlist allows you to specify the events that the key can fire, and which IPs can use the key. If other events or IPs attempt to use the key, the API returns with a 403 status code.

Denylist

denylist allows you to specify events which the key cannot fire, or IPs which cannot use the key. If the key is used to attempt these events the API returns with a 403 status code.

Security

We recommend always using a filter for public-facing ingest keys. This ensures that public keys, like the keys you use on your website, can only send specific events that are not relevant to your internal processes.

Alternative authentication methods

If you'd prefer to send your ingest key in the request header instead of having the key in the URL, you can:

  • Send a POST request to https://inn.gs
  • Include the Authorization header with your key: Authorization: Bearer $KEY
  • The request body remains your event payload