Event API

Overview

Event also allows you to emit and transact on messages using the Event API.

Generate an Event API Key

Head over to the Secret Keys section in the Settings page:

1. Click the + Create secret key button

2. Name your Secret Key

3. Click Create

Ensure you store the test and live keys somewhere safe (like a password manager).

Authentication

To authenticate and use any of the below API endpoints, you'll need to pass an Event Secret Key in the headers.

Header	Value
X-Buildable-Secret	BUILDABLE_SECRET_KEY

API Endpoints

GET

Emit a custom event

post

Body

application/json

eventstringRequired

payloadobjectRequired

Responses

200

Emit Response

application/json

objectOptionalExample: {"status":"success","key":"2b4bc1689000424287d1e68e6e8cf3d1"}

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/emit

HTTPcURLJavaScriptPython

POST /emit HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "event": "",
  "payload": {}
}

{
  "status": "success",
  "key": "2b4bc1689000424287d1e68e6e8cf3d1"
}

Query Events

post

Body

application/json

eventNamestringRequired

txKeystringRequired

sincenumberRequired

platformstringOptional

labelstringOptional

txStatestring · enumOptionalDefault: does-not-existPossible values:

pagenumberOptionalDefault: 1

pageSizenumber · max: 100OptionalDefault: 10

Responses

200

Query Response

application/json

totalnumberOptional

pagenumberOptional

pageSizenumberOptional

totalPagesnumberOptional

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/query

HTTPcURLJavaScriptPython

POST /query HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "eventName": "",
  "txKey": "",
  "since": null,
  "platform": "",
  "label": "",
  "txState": "does-not-exist",
  "page": 1,
  "pageSize": 10
}

{
  "rows": [
    {
      "_id": "text",
      "key": "text",
      "eventName": "text",
      "environment": "text",
      "payload": null,
      "query": null,
      "headers": null,
      "createdAt": 1,
      "state": "text",
      "history": [
        {
          "enterState": "text",
          "exitState": "text",
          "timestamp": 1,
          "updatedBy": "text"
        }
      ],
      "ttl": 1,
      "v": 1,
      "ownership": {
        "buildableId": "text",
        "userId": "text",
        "clientId": "text"
      },
      "processing": {
        "hasTransactions": true,
        "totalTransactions": 1,
        "hasFutureTransactions": true,
        "isCompleted": true
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Update Event

post

Body

application/json

keystringRequired

eventNamestringRequired

txKeystringRequired

txStatestring · enumRequiredExample: processingPossible values:

Responses

200

Update Response

application/json

_idstringRequired

keystringRequired

eventNamestringRequired

environmentstringRequired

payloadanyRequired

queryanyOptional

headersanyOptional

createdAtnumberRequired

statestringRequired

ttlnumberRequired

vnumberRequired

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/update

HTTPcURLJavaScriptPython

POST /update HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "key": "",
  "eventName": "",
  "txKey": "",
  "txState": "processing"
}

{
  "_id": "text",
  "key": "text",
  "eventName": "text",
  "environment": "text",
  "payload": null,
  "query": null,
  "headers": null,
  "createdAt": 1,
  "state": "text",
  "history": [
    {
      "enterState": "text",
      "exitState": "text",
      "timestamp": 1,
      "updatedBy": "text"
    }
  ],
  "ttl": 1,
  "v": 1,
  "ownership": {
    "buildableId": "text",
    "userId": "text",
    "clientId": "text"
  },
  "processing": {
    "hasTransactions": true,
    "totalTransactions": 1,
    "hasFutureTransactions": true,
    "isCompleted": true
  }
}

Initiate a transaction

post

Body

application/json

keystringRequired

txKeystringRequired

Responses

200

Init Response

application/json

_idstringRequired

keystringRequired

txnstringRequired

createdAtnumberRequired

ttlnumberRequired

statestringRequired

startedAtnumberRequired

txKeystringRequired

endedAtnumberOptional

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/init

HTTPcURLJavaScriptPython

POST /init HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "key": "",
  "txKey": ""
}

{
  "_id": "text",
  "key": "text",
  "txn": "text",
  "event": {
    "_id": "text",
    "eventName": "text"
  },
  "createdAt": 1,
  "ttl": 1,
  "state": "text",
  "history": [
    {
      "enterState": "text",
      "exitState": "text",
      "timestamp": 1,
      "updatedBy": "text"
    }
  ],
  "startedAt": 1,
  "txKey": "text",
  "endedAt": 1
}

Run a transaction

post

Body

application/json

keystringRequired

txKeystringRequired

outputstringOptional

statestring · enumRequiredExample: finishedPossible values:

Responses

200

Transact Response

application/json

_idstringRequired

keystringRequired

txnstringRequired

createdAtnumberRequired

ttlnumberRequired

statestringRequired

startedAtnumberRequired

txKeystringRequired

endedAtnumberOptional

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/transact

HTTPcURLJavaScriptPython

POST /transact HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "key": "",
  "txKey": "",
  "output": "",
  "state": "finished"
}

{
  "_id": "text",
  "key": "text",
  "txn": "text",
  "event": {
    "_id": "text",
    "eventName": "text"
  },
  "createdAt": 1,
  "ttl": 1,
  "state": "text",
  "history": [
    {
      "enterState": "text",
      "exitState": "text",
      "timestamp": 1,
      "updatedBy": "text"
    }
  ],
  "startedAt": 1,
  "txKey": "text",
  "endedAt": 1
}

Get the full event name

post

Body

application/json

eventNamestringRequired

platformstringOptional

labelstringOptional

Responses

200

Get Full Event Name Response

application/json

fullNamestringOptional

401

Unauthorized

application/json

422

Fields invalid

application/json

default

Server Error

application/json

post

/get-full-event-name

HTTPcURLJavaScriptPython

POST /get-full-event-name HTTP/1.1
Host: events.buildable.dev
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "eventName": "",
  "platform": "",
  "label": ""
}

{
  "fullName": "text"
}

Swagger

https://app.swaggerhub.com/apis-docs/paulkr/buildable-messages-api/1.0.0app.swaggerhub.com