Send events to Bekn

Anything your company runs can post events straight into a feed. Connect the Bekn API source in Bekn and every event you send arrives like one from any other connection: in its feed, counted in the day's activity, with a category Bekn decides.

For your agent

Everything on this page in one block. Give it to your agent or assistant and it can do the integrating.

Send events to Bekn.

Endpoint: POST https://api.bekn.co/v1/events
Auth: header "Authorization: Bearer <api key>", the key an admin reveals on the Bekn API connection in Bekn.
Body: JSON { "events": [ ... ] }, 1 to 100 events a request, 32 KiB an event, 1 MiB a request, at most 600 events a minute per connection.

Each event:
- id (string, required, up to 200 chars): the event's id in your system. The same id again is the same event, so retrying a batch is safe.
- name (string, required, up to 100 chars): the event type, lowercase words joined by dots, dashes or underscores, e.g. invoice.paid.
- summary (string, required, up to 280 chars): one readable line, what a person sees in the feed.
- occurredAt (string, optional): ISO 8601 with an offset; defaults to the time received.
- amount (object, optional): { "value": integer minor units, "currency": ISO 4217 code }.
- actor (object, optional): { "id": string, "name": string }, who did it.
- subject (object, optional): { "id": string, "name": string }, what it was done to.
- data (object, optional): anything else.
Do not send a category; Bekn decides it from the name and summary (revenue, customers, work, conversation, engineering, usage, system).

Responses: 202 { "accepted": n } every event stored; 401 bad or missing key; 413 request over 1 MiB; 422 an event broke a rule, nothing stored, issues listed by path such as events.1.name; 429 rate limited, nothing stored, retry after the Retry-After seconds.

Example:
curl -X POST https://api.bekn.co/v1/events \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "id": "inv-1001", "name": "invoice.paid", "summary": "Invoice #1001 paid by Acme", "amount": { "value": 4900, "currency": "USD" } } ] }'

Endpoint

POST https://api.bekn.co/v1/events

The body is JSON: an object with an events list of one to one hundred events.

Authentication

Every request carries the connection's API key as a bearer token. An admin finds it on the connection in Bekn, behind Reveal. The key is the connection's credential, so treat it like a password; disconnecting the connection ends it.

Example request

curl -X POST https://api.bekn.co/v1/events \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "id": "inv-1001",
        "name": "invoice.paid",
        "summary": "Invoice #1001 paid by Acme",
        "amount": { "value": 4900, "currency": "USD" }
      }
    ]
  }'

{ "accepted": 1 }

Fields

id string: Required. The event's id in your system, up to 200 characters. Sending the same id again is the same event, so a retry of a whole batch is safe.
name string: Required. The event type, lowercase words joined by dots, dashes or underscores, such as invoice.paid, up to 100 characters. Feeds narrow by it.
summary string: Required. One readable line, what a person sees in the feed, up to 280 characters.
occurredAt string: Optional. When it happened, ISO 8601 with an offset, such as 2026-10-22T09:30:00+01:00. Without it, the time Bekn received the event.
amount object: Optional. Money involved: value in minor units as an integer and currency as an ISO 4217 code, such as { "value": 4900, "currency": "USD" }. Summed per currency in the day's activity.
actor object: Optional. Who did it: an id and a display name, each up to 200 characters.
subject object: Optional. What it was done to: an id and a display name, each up to 200 characters.
data object: Optional. Anything else, as a JSON object. Shown with the event, nested objects as rows.

Responses

202 accepted: Every event is stored. The count is what you sent, duplicates included; they are already in.
401 unauthorized: The key is missing, wrong, or its connection is no longer active.
413 payload_too_large: The request is over 1 MiB.
422 invalid_body: An event broke a rule and nothing in the request was stored. The body lists each issue with its path, such as events.1.name.
429 rate_limited: More than 600 events in a minute for the connection, and nothing was stored. Retry-After says how many seconds to wait.

Limits

100 events a request
32 KiB an event
1 MiB a request
600 events a minute, per connection