UbSub API Reference

Introduction

The UbSub API is if you want to interface with the router and programatically introduce/modify/delete topics and subscriptions.

You do not need this API to send and listen to normal events. You can control everything you need using the UbSub UI.

About Swagger

You can find the swagger JSON document here.

You can read more about swagger on their website.

Authentication

All API calls are authenticated via a Bearer token on the header. You can get your user's token via your dashboard (and generate one if it doesn't exist). You can also substitute an API Token and secret from the user and bearer as well. The token may have limited permissions and not allowed to access every endpoint.

Example:

Authorization: Bearer <my user token>

Note: The user API is not currently open to call at the moment, and is only used by the UI.

API Endpoint
https://router.ubsub.io/api/v1
Terms of Service: https://ubsub.io
Contact: admin@ubsub.io
Schemes: https
Version: 0.1.0

Authentication

token

name
Authorization
in
header

OAuth2

flow
accessCode
authorizationUrl
https://app.ubsub.io/oidc
tokenUrl
https://app.ubsub.io/oidc/token

event

Events are both sent and recorded in the database for later use.

event

Get events

GET /user/{userId}/events

Get searchable events for a given user

userId

ID of the user

type
string
in
path
topic_id

Topic ID to limit results by

type
string
in
query
limit

Limit to number of events returned. Max: 500

type
integer 100
in
query
offset

Offset to start reading events

type
integer
in
query
order

What field to order the results by

type
string createdAt
in
query
direction

Direction in which to return the ordered fields

type
string DESC
in
query
before

Events before (less-than) the date

type
string (date-time)
in
query
after

Events after (greater than or equal to) the date

type
string (date-time)
in
query
search

Searches the payload for a case-insensitive partial match

type
string
in
query
fields

Comma-separated list of extra fields to populate

type
string , x ∈ { responses , topic }
in
query
200 OK
Event

Events retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
[
  {
    "createdAt": "string (date-time)",
    "updatedAt": "string (date-time)",
    "id": "string",
    "topic_id": "string",
    "user_id": "string",
    "payload": "string",
    "delivery_count": "integer",
    "responses": [
      {
        "createdAt": "string (date-time)",
        "updatedAt": "string (date-time)",
        "id": "string",
        "event_id": "string",
        "user_id": "string",
        "subscription_id": "string",
        "payload": "string"
      }
    ],
    "topic": "object"
  }
]
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token event , event.*
event

Get Time Series

GET /user/{userId}/events/timeseries

Get time series data about your events

userId

ID of the user

type
string
in
path
topic_id

Topic ID to limit results by

type
string
in
query
after

Events after (greater than or equal to) the date

type
string (date-time) 1 Day Ago
in
query
before

Events before (less than) the date

type
string (date-time) now
in
query
bucket

How to bucket the date in the time series

type
string , x ∈ { year , quarter , months , weeks , days , hours , minutes , seconds }
in
query
200 OK
EventTimeSeries

Time-series data

Response Example (200 OK) 
[
  {
    "topic_id": "string",
    "bucket": "string",
    "count": "integer"
  }
]
token event.aggr , event.*
event

Emit Event

POST /user/{userId}/events/{topicId}

Emits an event on a topic. Similar to the external ingress points, this will send to all subscribes. Unlike the ingress points, there is no fancy payload parsing or managing. All input must be json

userId

ID of the user

type
string
in
path
topicId

ID of topic to emit to

type
string
in
path
Request Example
"object"
token event.emit , event.emit.{topicId} , event.*

user

Users can currently be created and modified only by the UI. They are the base of all other API calls that can happen.

user

Create User

POST /user

Create a new user with an email and password

UserCreate

User object

Request Example
{
  "email": "string (email)",
  "password": "string (password)"
}
200 OK
User

Topic created

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "email": "string (email)",
  "secret": "string",
  "passwordless": "boolean"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token app
user

Get User

GET /user/{userId}

Get a user by their id

userId

ID of the user

type
string
in
path
200 OK
User

User retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "email": "string (email)",
  "secret": "string",
  "passwordless": "boolean"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token user
user

Update user

PATCH /user/{userId}

Update user information

UserUpdate

User update

userId

ID Of the user

type
string
in
path
Request Example
{
  "password": "string (password)"
}
200 OK
User

User updated

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "email": "string (email)",
  "secret": "string",
  "passwordless": "boolean"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token user.update.password

topic

Topics can be created/modified/deleted for a given user. They are what are invoked and distribute requests to their subscribers.

topic

Create Topic

POST /user/{userId}/topic

Create a new topic for a user

TopicCreate

Topic object

userId

ID of the user

type
string
in
path
Request Example
{
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string"
}
200 OK
Topic

Topic created

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string",
  "id": "string",
  "user_id": "string",
  "subscriptions": [
    {
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "name": "string",
      "key": "string",
      "method": "string",
      "uri": "string",
      "template_id": "string",
      "volatile": "boolean",
      "retry": "boolean",
      "enabled": "boolean",
      "id": "string"
    }
  ]
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token topic.create , topic.*
topic

Get Topics

GET /user/{userId}/topic

Get all topics for a given user

userId

ID of the user

type
string
in
path
200 OK
Topic

Topic retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
[
  {
    "createdAt": "string (date-time)",
    "updatedAt": "string (date-time)",
    "name": "string",
    "key": "string",
    "async": "boolean",
    "transient": "boolean",
    "template_id": "string",
    "id": "string",
    "user_id": "string",
    "subscriptions": [
      {
        "createdAt": "string (date-time)",
        "updatedAt": "string (date-time)",
        "name": "string",
        "key": "string",
        "method": "string",
        "uri": "string",
        "template_id": "string",
        "volatile": "boolean",
        "retry": "boolean",
        "enabled": "boolean",
        "id": "string"
      }
    ]
  }
]
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token topic , topic.*
topic

Get Topic by Id

GET /user/{userId}/topic/{topicId}

Retrieves a topic given its user and topic id

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
200 OK
Topic

Topic retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string",
  "id": "string",
  "user_id": "string",
  "subscriptions": [
    {
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "name": "string",
      "key": "string",
      "method": "string",
      "uri": "string",
      "template_id": "string",
      "volatile": "boolean",
      "retry": "boolean",
      "enabled": "boolean",
      "id": "string"
    }
  ]
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token topic , topic.{topicId} , topic.*
topic

Update topic

PATCH /user/{userId}/topic/{topicId}

Update topic configuration

TopicUpdate

Topic object

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
Request Example
{
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string"
}
200 OK
Topic

Topic updated

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string",
  "id": "string",
  "user_id": "string",
  "subscriptions": [
    {
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "name": "string",
      "key": "string",
      "method": "string",
      "uri": "string",
      "template_id": "string",
      "volatile": "boolean",
      "retry": "boolean",
      "enabled": "boolean",
      "id": "string"
    }
  ]
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token topic.update , topic.update.{topicId} , topic.*
topic

Delete a topic by id

DELETE /user/{userId}/topic/{topicId}

Deletes a topic given its user and topic id

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
200 OK

Topic deleted

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token topic.delete , topic.*

subscription

Subscribers receive messages from topics that they are connected to. They can have various URI types and protocols. See the main documentation for details on supported protocols.

subscription

Create subscription

POST /user/{userId}/topic/{topicId}/subscription

Create a new subscription on a topic

SubscriptionCreate

Subscription object

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
Request Example
{
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean"
}
200 OK
Subscription

Subscription created

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean",
  "id": "string"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token subscription.create , subscription.create.{topicId} , subscription.*
subscription

Update subscription

PATCH /user/{userId}/topic/{topicId}/subscription/{subscriptionId}

Update details of a subscription

SubscriptionUpdate

Subscription update

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
subscriptionId

ID of the subscription

type
string
in
path
Request Example
{
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean"
}
200 OK
Subscription

Subscription updated

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean",
  "id": "string"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token subscription.update , subscription.update.{topicId} , subscription.*
subscription

Delete subscription

DELETE /user/{userId}/topic/{topicId}/subscription/{subscriptionId}

Delete a subscription on a topic

userId

ID of the user

type
string
in
path
topicId

ID of the topic

type
string
in
path
subscriptionId

ID of the subscription

type
string
in
path
200 OK

Subscription deleted

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token subscription.delete , subscription.delete.{topicId} , subscription.*

template

Templates have the ability to process against events, either validating them, or mapping their contents to another form

template

Create Template

POST /user/{userId}/template

Create a new template code

TemplateCreate

Template definition

userId

ID of the user

type
string
in
path
Request Example
{
  "name": "string",
  "language": "string",
  "source": "string"
}
200 OK
Template

Templated created

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "id": "string",
  "owner_user_id": "string",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "language": "string",
  "source": "string"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template.create , template.*
template

Get templates

GET /user/{userId}/template

Get all templates useable by user, including global templates

userId

ID of the user

type
string
in
path
200 OK
Template

Template retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
[
  {
    "id": "string",
    "owner_user_id": "string",
    "createdAt": "string (date-time)",
    "updatedAt": "string (date-time)",
    "name": "string",
    "language": "string",
    "source": "string"
  }
]
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template , template.{templateId} , template.*
template

Get template

GET /user/{userId}/template/{templateId}

Get a template by id

userId

ID of the user

type
string
in
path
templateId

Id of template

type
string
in
path
200 OK
Template

Template retrieved

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "id": "string",
  "owner_user_id": "string",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "language": "string",
  "source": "string"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template , template.*
template

Update template

PATCH /user/{userId}/template/{templateId}

Update code of a template

Template

Template definition

userId

ID of the user

type
string
in
path
templateId

Id of template

type
string
in
path
Request Example
{
  "id": "string",
  "owner_user_id": "string",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "language": "string",
  "source": "string"
}
200 OK
Template

Templated updated

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "id": "string",
  "owner_user_id": "string",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "language": "string",
  "source": "string"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template.update , template.update.{templateId} , template.*
template

Delete template

DELETE /user/{userId}/template/{templateId}

Delete a template that belongs to you

userId

ID of the user

type
string
in
path
templateId

Id of template

type
string
in
path
200 OK

Template deleted

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template.delete , template.*
template

Evaluate payload

POST /user/{userId}/template/{templateId}/event

Post event payload to evaluate with template

Body to evaluate against the template

payload: string

Payload to evaluate

userId

ID of the user

type
string
in
path
templateId

Id of template

type
string
in
path
Request Example
{
  "payload": "string"
}
200 OK

Templated evaluated

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
"object"
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token template.exec , template.exec.{templateId}

Token

Endpoint to control authorization tokens and their scopes.

Token

Get all tokens

GET /user/{userId}/token

Get all tokens belong to the user

userId

ID of the user

type
string
in
path
client_id

If specified, returns a list of 1 or 0 elements for the matching client

type
string
in
query
200 OK
ApiToken

Tokens

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
[
  {
    "createdAt": "string (date-time)",
    "updatedAt": "string (date-time)",
    "name": "string",
    "scope": "string",
    "id": "string",
    "secret": "string",
    "user_id": "string",
    "client_id": "string",
    "last_used": "string (date-time)"
  }
]
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token token , token.*
Token

Create new token

POST /user/{userId}/token

Create a new token for the current user

ApiTokenCreate

Api Token Creation

userId

ID of the user

type
string
in
path
Request Example
{
  "name": "string",
  "scope": "string",
  "client_id": "string"
}
200 OK
ApiToken

Created token

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "scope": "string",
  "id": "string",
  "secret": "string",
  "user_id": "string",
  "client_id": "string",
  "last_used": "string (date-time)"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token token.create , token.*
Token

Get token

GET /user/{userId}/token/{tokenId}

Get a single token for a user

userId

ID of the user

type
string
in
path
tokenId

ID of the token

type
string
in
path
200 OK
ApiToken

Token

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "scope": "string",
  "id": "string",
  "secret": "string",
  "user_id": "string",
  "client_id": "string",
  "last_used": "string (date-time)"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token token , token.*
Token

Update token

PATCH /user/{userId}/token/{tokenId}

Update mutable attributes of a token

ApiTokenUpdate

Api Token Update

userId

ID of the user

type
string
in
path
tokenId

ID of the token

type
string
in
path
Request Example
{
  "name": "string",
  "scope": "string"
}
200 OK
ApiToken

Token

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "scope": "string",
  "id": "string",
  "secret": "string",
  "user_id": "string",
  "client_id": "string",
  "last_used": "string (date-time)"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token token.update , token.*
Token

Delete token

DELETE /user/{userId}/token/{tokenId}

Delete a single token for a user

userId

ID of the user

type
string
in
path
tokenId

ID of the token

type
string
in
path
200 OK
ApiResponse

Token

400 Bad Request
ApiResponse

Invalid input

401 Unauthorized
ApiResponse

Authorization denied

404 Not Found
ApiResponse

Object not found

500 Internal Server Error

Something unexpected happened

Response Example (200 OK) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (400 Bad Request) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (401 Unauthorized) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
Response Example (404 Not Found) 
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}
token token.delete , token.*

ingress

Router API event ingress point. These are the public ways to ingest events into the router. Note: The common /api/v1 prefix is not needed on this endpoint.

ingress

Send event as user

POST /event/{userId}/{topicNameOrId}

NOTE: Unlike other API endpoints, this one is not versioned on /api/v1/ Send an event to a topic. Any http method is allowed to trigger this (get, post, patch, put, etc..). Note that this method doesn't require traditional authentication like many of the other ones so that it may be triggered externally. For an API-driven event, see "Send event API"

userId

ID of the user to send the event to

type
string
in
path
topicNameOrId

Topic can be passed by name or by id when the userId is present

type
string
in
path
key

The key for the topic, if needed. Alternatively can be on the Authorization header

type
string
in
query
200 OK

Success

400 Bad Request

Bad request or circular chain detected

401 Unauthorized

Bad authorization or key

ingress

Send event by topic

POST /event/{topicId}

Note: Unlike other API endpoints, this one is not versioned on /api/v1/ Send an event to a topicId, forging the userId for a shortened url. Can't use topic-name (since it is no longer uniquely identifying).

topicId

Topic can be passed by name or by id when the userId is present

type
string
in
path
key

The key for the topic, if needed. Alternatively can be on the Authorization header

type
string
in
query
200 OK

Success

400 Bad Request

Bad request or circular chain detected

401 Unauthorized

Authorization denied

docs

Self-documenting endpoints

docs

Swagger definition

GET /docs/v2/swagger

Get swagger document (Used to generate this)

200 OK

The swagger document

docs

Router Readme

GET /docs/v2/readme

Get the markdown readme for the router

200 OK

The router readme

docs

Router Public Certificate

GET /docs/cert

Get the public certificate used to sign requests from the router

200 OK

The router cert

docs

Routing protocols

GET /docs/protocols

Returns the set of protocols supported by the router

200 OK
Protocols

Supported protocols

Response Example (200 OK) 
{
  "protocolName": {
    "handler": "string",
    "description": "string"
  }
}
docs

Templating languages

GET /docs/languages

Returns the set of supported templating languages

200 OK
Language

Set of templating languages

Response Example (200 OK) 
[
  {
    "language": "string",
    "description": "string"
  }
]

Schema Definitions

User: object

User object

createdAt: string (date-time)
updatedAt: string (date-time)
id: string

ShortId user id

email: string (email)

User email address

secret: string

API Secret

passwordless: boolean

Whether or not the user is passwordless/userless

Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "email": "string (email)",
  "secret": "string",
  "passwordless": "boolean"
}

UserUpdate: object

User update

password: string (password)

User password (will be hashed)

Example
{
  "password": "string (password)"
}

UserCreate: object

User object

email: string (email)

User email address

password: string (password)

User password (hashed). Non-retrieveable

Example
{
  "email": "string (email)",
  "password": "string (password)"
}

ApiTokenUpdate: object

name: string

Name of the api token, such as its use

scope: string

Space-separated list of requested access scope

Example
{
  "name": "string",
  "scope": "string"
}

ApiTokenCreate: object

name: string

Name of the api token, such as its use

scope: string

Space-separated list of requested access scope

client_id: string

Optional client Id the token belongs to, must be unique or null

Example
{
  "name": "string",
  "scope": "string",
  "client_id": "string"
}

ApiToken: object

createdAt: string (date-time)
updatedAt: string (date-time)
name: string

Name of the api token, such as its use

scope: string

Space-separated list of requested access scope

id: string 24 bytes in hex encoding

Generated token id

secret: string 24 bytes in hex encoding

Generated token secret

user_id: string

User the token belongs to

client_id: string

Client Id the token belongs to, can only be read once set

last_used: string (date-time)

Last time the token was used via an API call

Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "scope": "string",
  "id": "string",
  "secret": "string",
  "user_id": "string",
  "client_id": "string",
  "last_used": "string (date-time)"
}

TopicCreate: object

name: string

Name of the topic. Alphanumeric

key: string true

Shared key to access topic. When creating, if the key is true it will be generated. false or null will be blank.

async: boolean false

If true, an event posted to the topic will not wait for the response before returning

transient: boolean false

If true, events won't be written to the database. NOTE: Cannot retry events that are transient

template_id: string null

Id of the template to execute against an event sent to this topic

Example
{
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string"
}

TopicUpdate: object

name: string

Name of the topic. Alphanumeric

key: string true

Shared key to access topic. When creating, if the key is true it will be generated. false or null will be blank.

async: boolean false

If true, an event posted to the topic will not wait for the response before returning

transient: boolean false

If true, events won't be written to the database. NOTE: Cannot retry events that are transient

template_id: string null

Id of the template to execute against an event sent to this topic

Example
{
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string"
}

Topic: object

createdAt: string (date-time)
updatedAt: string (date-time)
name: string

Name of the topic. Alphanumeric

key: string true

Shared key to access topic. When creating, if the key is true it will be generated. false or null will be blank.

async: boolean false

If true, an event posted to the topic will not wait for the response before returning

transient: boolean false

If true, events won't be written to the database. NOTE: Cannot retry events that are transient

template_id: string null

Id of the template to execute against an event sent to this topic

id: string

ShortId of the topic

user_id: string

User the topic belongs to

subscriptions: object[]
Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "async": "boolean",
  "transient": "boolean",
  "template_id": "string",
  "id": "string",
  "user_id": "string",
  "subscriptions": [
    {
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "name": "string",
      "key": "string",
      "method": "string",
      "uri": "string",
      "template_id": "string",
      "volatile": "boolean",
      "retry": "boolean",
      "enabled": "boolean",
      "id": "string"
    }
  ]
}

SubscriptionCreate: object

name: string

Human-readable description of the subscription

key: string null

Shared key sent to the subscriber upon invocation

method: string , x ∈ { GET , POST (default) , PUT , PATCH , DELETE , SOURCE }

HTTP Method to invoke the endpoint with. SOURCE is special, and will copy the the invocation method

uri: string

The URI to be invoked. Can be any supported URI types (See subscription docs)

template_id: string null

The id of the template to invoke ont he payload before sending to the destination

volatile: boolean false

If true, the subscription will be removed automatically and immediately upton the first failure to call the endpoint

retry: boolean false

If true, the subscription will be queued for retry if there is an error posting to it. eg a non-2xx

enabled: boolean true

If false, the subscription will not be triggered on an incoming event

Example
{
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean"
}

SubscriptionUpdate: object

name: string

Human-readable description of the subscription

key: string null

Shared key sent to the subscriber upon invocation

method: string , x ∈ { GET , POST (default) , PUT , PATCH , DELETE , SOURCE }

HTTP Method to invoke the endpoint with. SOURCE is special, and will copy the the invocation method

uri: string

The URI to be invoked. Can be any supported URI types (See subscription docs)

template_id: string null

The id of the template to invoke ont he payload before sending to the destination

volatile: boolean false

If true, the subscription will be removed automatically and immediately upton the first failure to call the endpoint

retry: boolean false

If true, the subscription will be queued for retry if there is an error posting to it. eg a non-2xx

enabled: boolean true

If false, the subscription will not be triggered on an incoming event

Example
{
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean"
}

Subscription: object

createdAt: string (date-time)
updatedAt: string (date-time)
name: string

Human-readable description of the subscription

key: string null

Shared key sent to the subscriber upon invocation

method: string , x ∈ { GET , POST (default) , PUT , PATCH , DELETE , SOURCE }

HTTP Method to invoke the endpoint with. SOURCE is special, and will copy the the invocation method

uri: string

The URI to be invoked. Can be any supported URI types (See subscription docs)

template_id: string null

The id of the template to invoke ont he payload before sending to the destination

volatile: boolean false

If true, the subscription will be removed automatically and immediately upton the first failure to call the endpoint

retry: boolean false

If true, the subscription will be queued for retry if there is an error posting to it. eg a non-2xx

enabled: boolean true

If false, the subscription will not be triggered on an incoming event

id: string

ShortId of the subscription

Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "key": "string",
  "method": "string",
  "uri": "string",
  "template_id": "string",
  "volatile": "boolean",
  "retry": "boolean",
  "enabled": "boolean",
  "id": "string"
}

TemplateCreate: object

name: string

Human-readable name of the template

language: string , x ∈ { VALID:KEYS }

Language the template is in

source: string

The source code for the template

Example
{
  "name": "string",
  "language": "string",
  "source": "string"
}

TemplateUpdate: object

name: string

Human-readable name of the template

language: string , x ∈ { VALID:KEYS }

Language the template is in

source: string

The source code for the template

Example
{
  "name": "string",
  "language": "string",
  "source": "string"
}

Template: object

id: string

ID of the template

owner_user_id: string

The owner of the template. If null, is global template

createdAt: string (date-time)
updatedAt: string (date-time)
name: string

Human-readable name of the template

language: string , x ∈ { VALID:KEYS }

Language the template is in

source: string

The source code for the template

Example
{
  "id": "string",
  "owner_user_id": "string",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "name": "string",
  "language": "string",
  "source": "string"
}

Event: object

createdAt: string (date-time)
updatedAt: string (date-time)
id: string

UUID of event

topic_id: string

Owning topic id

user_id: string

Owning user id

payload: string

Raw payload of the event

delivery_count: integer

Number of times the event was attempted delivered

responses: object[]

(Optional) Array of responses returned to the event

topic: object

(Optional) The topic object that the event belongs to

Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "topic_id": "string",
  "user_id": "string",
  "payload": "string",
  "delivery_count": "integer",
  "responses": [
    {
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "id": "string",
      "event_id": "string",
      "user_id": "string",
      "subscription_id": "string",
      "payload": "string"
    }
  ],
  "topic": "object"
}

EventResponse: object

createdAt: string (date-time)
updatedAt: string (date-time)
id: string

UUID Of the event response

event_id: string

UUID of the event that was responded to

user_id: string

ShortId of the user

subscription_id: string

ShortId of the subscription

payload: string

Raw payload of the response

Example
{
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "id": "string",
  "event_id": "string",
  "user_id": "string",
  "subscription_id": "string",
  "payload": "string"
}

EventTimeSeries: object

topic_id: string

Id of the topic

bucket: string

The bucket date-time

count: integer

The number of events that were published in the time bucket

Example
{
  "topic_id": "string",
  "bucket": "string",
  "count": "integer"
}

ApiResponse: object

statusCode: integer (int32)
message: string
error: string
Example
{
  "statusCode": "integer (int32)",
  "message": "A message describing the error",
  "error": "Information about an error"
}

Protocols: object

protocolName: object

The name of the protocol in the URI segment

Example
{
  "protocolName": {
    "handler": "string",
    "description": "string"
  }
}

Language: object

language: string

Language unique identifier

description: string

Short description of language

Example
{
  "language": "string",
  "description": "string"
}
Documentation by Spectacle