Create Event

Creates an Event in a named Channel, creating the Channel when necessary. When notify is true (the default), Organization members who turned on notifications for the Channel receive a web push notification. Events are retained for 90 days. Add actions with an id (buttons) or fields to ask a person something: the event waits for an answer (data.answer), which you read with GET /v1/events/{id}.

POST/v1/events

Authorization

AuthorizationBearer token (EmitKit API key) · headerrequired

EmitKit API key in the Authorization header as Bearer emitkit_…

X-API-KeyAPI key · headerrequired

EmitKit API key beginning with emitkit_.

Header parameters

Idempotency-Keystring

A caller-generated command identifier, scoped to the API key and kept for 24 hours. Reusing it with the same request replays the first response; reusing it with a different request, or while the first request is still running, returns 409.

min length 1 · max length 255

Request body

requiredapplication/json

actionsobject[]

Up to 4. A button { id, label, style?, requires? } is an answer: the event then waits for someone to press one. A link { label, url } only opens a page.

max items 4

Show properties

Array of object

idstring

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 40

requiresstring[]

Ids of text or multiple-choice fields that must be filled in before this button can be pressed.

stylestring

Allowed:primarydestructive

urlstring

A link: the page it opens

max length 2000

callbackUrlstring

Where EmitKit POSTs the answer (event.answered) or the expiry (event.expired), signed with the project's callback secret (Standard Webhooks). https only.

max length 2000

channelNamestringrequired

Channel name. The Channel is created automatically when it does not exist.

min length 1 · max length 255

descriptionstring

displayAsstring

Allowed:messagenotification

expiresIninteger

Seconds an event with buttons or fields waits for an answer: 10 to 604800, default 86400 (24 hours). After that, answer.status is expired.

min 10 · max 604800

fieldsobject[]

Up to 5 inputs the person fills in: a choice (one or several options), text, a number or a yes/no. The answer reports them in answer.values by field id. Fields without buttons get a Send button.

max items 5

Show properties

Array of object

Any of:

object

defaultstring | string[]

An option id (an array of ids when multiple). A single choice without one starts on its first option.

Show properties

Any of:

string

string

string[]

Array of string

string

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

multipleboolean

Let the person pick several options (checkboxes).

optionsobject[]required

min items 2 · max items 10

Show properties

Array of object

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

What the person sees

min length 1 · max length 100

typestringrequired

Allowed:choice

object

defaultstring

min length 0 · max length 2000

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

maxLengthinteger

min 1 · max 2000

multilineboolean

placeholderstring

min length 1 · max length 100

typestringrequired

Allowed:text

object

defaultnumber

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

maxnumber

minnumber

stepnumber

typestringrequired

Allowed:number

unitstring

Shown next to the value, e.g. $ or %

min length 1 · max length 8

object

defaultboolean

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

typestringrequired

Allowed:boolean

iconstring

metadataobject

notifyboolean

Send a web push notification to devices subscribed to the Channel.

default: true

resumestring

Your own state, sent back as is in the callback and GET /v1/events/{id}, so a serverless handler can carry on without a database. Never shown to people.

max length 65536

sourcestring

min length 1 · max length 255 · default: "api"

tagsstring[]

titlestringrequired

min length 1 · max length 1000

userIdstring | null

Responses

201

The Event was created or an earlier response was replayed.

dataEventrequired

An event, as createEvent, getEvent and cancelEvent return it: the event with its fields, actions (both [] when none) and answer (null when it doesn't wait). Events are kept for 90 days; after that getEvent returns 404.

Show properties

actionsobject[]required

The event's buttons and links ([] when none).

max items 4

Show properties

Array of object

idstring

A button: what the answer reports, e.g. approve

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 40

requiresstring[]

Field ids that must be filled in before this button can be pressed.

stylestring

Allowed:primarydestructive

urlstring

A link: the page it opens

max length 2000 · matches ^(?:https:\/\/|http:\/\/localhost[:/])\S+$

answerAnswer | anyrequired

null when the event doesn't wait for an answer.

Show properties

Any of:

Answer

actionstring | nullrequired

The id of the pressed button (submit when fields had no buttons).

atstring<date-time> | anyrequired

When it was answered.

Show properties

Any of:

string<date-time>

string<date-time>

any

any

byobject | anyrequired

Who answered (an organization member).

Show properties

Any of:

object

emailstringrequired

idstringrequired

namestringrequired

any

any

expiresAtstring<date-time>required

When a pending event stops waiting.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

statusstringrequired

Allowed:pendingansweredexpiredcanceled

urlstring<uri>required

The answer page (needs a signed-in member). Pushes for this event open it.

valuesobject | anyrequired

Field values by field id: an option id (an array for multiple), text, a number or a boolean. Empty text fields are left out.

Show properties

Any of:

object

object

any

any

any

any

callbackobject | anyrequired

How delivery to callbackUrl went; null without one.

Show properties

Any of:

object

attemptsintegerrequired

deliveredAtstring<date-time> | anyrequired

When a 2xx was received.

Show properties

Any of:

string<date-time>

string<date-time>

any

any

lastStatusinteger | nullrequired

The receiver's last HTTP status; null when it couldn't be reached.

urlstringrequired

any

any

channelIdstringrequired

channelNamestringrequired

createdAtstring<date-time>required

descriptionstring | nullrequired

displayAsstringrequired

Allowed:messagenotification

fieldsobject[]required

The event's fields ([] when none).

max items 5

Show properties

Array of object

Any of:

object

defaultstring | string[]

An option id (an array of ids when multiple). A single choice without one starts on its first option.

Show properties

Any of:

string

string

string[]

Array of string

string

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

multipleboolean

Let the person pick several options (checkboxes).

optionsobject[]required

min items 2 · max items 10

Show properties

Array of object

idstringrequired

What the answer reports, e.g. partial

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

What the person sees

min length 1 · max length 100

typestringrequired

Allowed:choice

object

defaultstring

min length 0 · max length 2000

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

maxLengthinteger

min 1 · max 2000

multilineboolean

placeholderstring

min length 1 · max length 100

typestringrequired

Allowed:text

object

defaultnumber

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

maxnumber

minnumber

stepnumber

typestringrequired

Allowed:number

unitstring

Shown next to the value, e.g. $ or %

min length 1 · max length 8

object

defaultboolean

idstringrequired

matches ^[A-Za-z0-9_-]{1,64}$

labelstringrequired

min length 1 · max length 100

typestringrequired

Allowed:boolean

iconstring | nullrequired

idstringrequired

metadataobjectrequired

notifybooleanrequired

resumestring | nullrequired

The resume you sent, as is (null without one).

sourcestringrequired

tagsstring[]required

titlestringrequired

userIdstring | nullrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

400

The request does not match the operation contract.

codestringrequired

Stable: switch on this, not on error or message.

detailsobject[]required

Show properties

Array of object

codestring

min length 1

messagestringrequired

min length 1

pathstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

errorstringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

401

Authentication credentials are missing or invalid.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

403

The API key lacks this operation's scope (a read-only key can only read), isn't bound to a Project, or its Project was deleted.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

What's missing, e.g. the scope the operation needs.

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

409

The Idempotency-Key belongs to a different event request.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

413

The request body exceeds 1 MiB, or the stored Event would exceed the 16 KB limit (all of its stored fields, including metadata, combined).

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

Allowed:Request body exceeds the 1 MiB limitEvent exceeds the 16 KB storage limit

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

429

The authenticated principal exceeded its rate limit.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

500

The Event could not be created.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (EmitKit API key)Remember on this deviceInclude my values in samples

Parameters

Idempotency-KeyheaderA caller-generated command identifier, scoped to the API key and kept for 24 hours. Reusing it with the same request replays the first response; reusing it with a different request, or while the first request is still running, returns 409.

Bodyapplication/json

Request body

Request

curl -X POST "https://api.emitkit.com/v1/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "channelName": "refunds",
  "title": "Refund Jane Cooper for order #1042?",
  "description": "Arrived damaged: 2 of 3 items broken.",
  "fields": [
    {
      "id": "resolution",
      "type": "choice",
      "label": "Resolution",
      "options": [
        {
          "id": "full",
          "label": "Full refund ($240)"
        },
        {
          "id": "partial",
          "label": "Broken items only ($160)"
        }
      ],
      "default": "partial"
    },
    {
      "id": "note",
      "type": "text",
      "label": "Note to Jane",
      "multiline": true
    }
  ],
  "actions": [
    {
      "id": "approve",
      "label": "Refund",
      "style": "primary"
    },
    {
      "id": "deny",
      "label": "Don'\''t refund",
      "style": "destructive",
      "requires": [
        "note"
      ]
    },
    {
      "label": "Open order",
      "url": "https://shop.example.com/admin/orders/1042"
    }
  ],
  "expiresIn": 1800
}'

const response = await fetch("https://api.emitkit.com/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"channelName\": \"refunds\",\n  \"title\": \"Refund Jane Cooper for order #1042?\",\n  \"description\": \"Arrived damaged: 2 of 3 items broken.\",\n  \"fields\": [\n    {\n      \"id\": \"resolution\",\n      \"type\": \"choice\",\n      \"label\": \"Resolution\",\n      \"options\": [\n        {\n          \"id\": \"full\",\n          \"label\": \"Full refund ($240)\"\n        },\n        {\n          \"id\": \"partial\",\n          \"label\": \"Broken items only ($160)\"\n        }\n      ],\n      \"default\": \"partial\"\n    },\n    {\n      \"id\": \"note\",\n      \"type\": \"text\",\n      \"label\": \"Note to Jane\",\n      \"multiline\": true\n    }\n  ],\n  \"actions\": [\n    {\n      \"id\": \"approve\",\n      \"label\": \"Refund\",\n      \"style\": \"primary\"\n    },\n    {\n      \"id\": \"deny\",\n      \"label\": \"Don't refund\",\n      \"style\": \"destructive\",\n      \"requires\": [\n        \"note\"\n      ]\n    },\n    {\n      \"label\": \"Open order\",\n      \"url\": \"https://shop.example.com/admin/orders/1042\"\n    }\n  ],\n  \"expiresIn\": 1800\n}"
});

import requests

response = requests.post(
    "https://api.emitkit.com/v1/events",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"channelName\": \"refunds\",\n  \"title\": \"Refund Jane Cooper for order #1042?\",\n  \"description\": \"Arrived damaged: 2 of 3 items broken.\",\n  \"fields\": [\n    {\n      \"id\": \"resolution\",\n      \"type\": \"choice\",\n      \"label\": \"Resolution\",\n      \"options\": [\n        {\n          \"id\": \"full\",\n          \"label\": \"Full refund ($240)\"\n        },\n        {\n          \"id\": \"partial\",\n          \"label\": \"Broken items only ($160)\"\n        }\n      ],\n      \"default\": \"partial\"\n    },\n    {\n      \"id\": \"note\",\n      \"type\": \"text\",\n      \"label\": \"Note to Jane\",\n      \"multiline\": true\n    }\n  ],\n  \"actions\": [\n    {\n      \"id\": \"approve\",\n      \"label\": \"Refund\",\n      \"style\": \"primary\"\n    },\n    {\n      \"id\": \"deny\",\n      \"label\": \"Don't refund\",\n      \"style\": \"destructive\",\n      \"requires\": [\n        \"note\"\n      ]\n    },\n    {\n      \"label\": \"Open order\",\n      \"url\": \"https://shop.example.com/admin/orders/1042\"\n    }\n  ],\n  \"expiresIn\": 1800\n}",
)

Response

{
  "data": {
    "actions": [
      {
        "id": "string",
        "label": "string",
        "requires": [
          "string"
        ],
        "style": "primary",
        "url": "string"
      }
    ],
    "answer": {
      "action": "string",
      "at": "2019-08-24T14:15:22Z",
      "by": {
        "email": "string",
        "id": "string",
        "name": "string"
      },
      "expiresAt": "2019-08-24T14:15:22Z",
      "status": "pending",
      "url": "http://example.com",
      "values": {
        "property1": "string",
        "property2": "string"
      }
    },
    "callback": {
      "attempts": 0,
      "deliveredAt": "2019-08-24T14:15:22Z",
      "lastStatus": 0,
      "url": "string"
    },
    "channelId": "string",
    "channelName": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "description": "string",
    "displayAs": "message",
    "fields": [
      {
        "default": "string",
        "id": "string",
        "label": "string",
        "multiple": true,
        "options": [
          {
            "id": "string",
            "label": "string"
          },
          {
            "id": "string",
            "label": "string"
          }
        ],
        "type": "choice"
      }
    ],
    "icon": "string",
    "id": "string",
    "metadata": {},
    "notify": true,
    "resume": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "title": "string",
    "userId": "string"
  },
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": true
}

{
  "code": "validation_error",
  "details": [
    {
      "code": "string",
      "message": "string",
      "path": [
        "string"
      ]
    }
  ],
  "error": "Validation error",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "unauthorized",
  "error": "Unauthorized",
  "message": "Invalid or missing authentication credentials",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "forbidden",
  "error": "Forbidden",
  "message": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "idempotency_conflict",
  "error": "Idempotency conflict",
  "message": "This idempotency key was already used with a different request",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "payload_too_large",
  "error": "Payload too large",
  "message": "Request body exceeds the 1 MiB limit",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "rate_limited",
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "internal_error",
  "error": "Failed to create event",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}