Event streams

The following endpoints enable you to manage event topics.

API DOMAIN AND NAMESPACE DIFFERENCES FOR EVENT STREAMS

The Event streams APIs are divided into two categories. Each category uses a different domain and namespace.

Public API

The following endpoints use the event-streams domain:

Consume messages POST /api/v1/topics/:topic_id/consume
Publish a message POST /api/v1/topics/:topic_id/publish
Publish a batch of messages POST /api/v1/batch/topics/:topic_id/publish

Refer to the Event streams public API documentation for more information.

Developer API

The following endpoints use the standard Developer API base URL:

List topics GET /api/event_streams/topics
Create a topic POST /api/event_streams/topics
Get a topic by ID GET /api/event_streams/topics/:topic_id
Update a topic PUT /api/event_streams/topics/:topic_id
Purge a topic PUT /api/event_streams/topics/:topic_id/purge
Delete a topic DELETE /api/event_streams/topics/:topic_id

Rate limits

Event streams developer API resources have the following rate limits:

Type	Resource	Quota
All	All Event streams endpoints	60 requests per minute

Additionally, Event streams developer API resources have the following payload quota:

Type	Resource	Quota
All	All Event streams endpoints	Maximum payload size: 1 MB

Quick reference

Type	Resource	Description
GET	/api/event_streams/topics	Retrieve a list of topics.
POST	/api/event_streams/topics	Create a topic.
GET	/api/event_streams/topics/:topic_id	Get topic by ID.
PUT	/api/event_streams/topics/:topic_id	Update a topic.
PUT	/api/event_streams/topics/:topic_id/purge	Purge a topic.
DELETE	/api/event_streams/topics/:topic_id	Delete a topic.

BEST PRACTICE

For endpoints that modify topics (create and update), we recommend that you define parameters in the request body instead of the URL.

List topics

Retrieves a list of event topics, with optional filtering, sorting, and the ability to include topic schemas in the response.

GET https://YOUR_DATA_CENTER/api/event_streams/topics

Query parameters

Name	Type	Description
name	string optional	Filters event topics by a case-sensitive title. Supports partial matching, which means you can search for fragments of the title.
sort	string optional	Defines how to sort the results. Options include `activity` (most recent activity first), `name`, and `id`. Set to `id` by default.
include_schema	boolean optional	When set to `true`, the schema of each event topic is included in the response payload. Set to `false` by default.

Sample request

This request retrieves event topics that contain the keyword Order within the name. The results are sorted by event topic ID, and the schema for each event topic is included in the response payload.

shell

curl  -X GET "https://YOUR_DATA_CENTER/api/event_streams/topics?name=:name_value&sort=:sort_value&include_schema=:include_schema_value" \
      -H 'Authorization: Bearer <api_token>'

Response

json

{
    "count": 2,
    "data": [
        {
            "id": 334525,
            "name": "Order placed",
            "created_at": "2024-09-25T09:47:54.089-07:00",
            "updated_at": "2024-09-25T09:47:54.089-07:00",
            "retention": 604800,
            "schema": [
                {
                    "control_type": "text",
                    "label": "Order ID",
                    "name": "OrderId",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "text",
                    "label": "Customer ID",
                    "name": "CustomerId",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "text",
                    "label": "Amount",
                    "name": "Amount",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "date",
                    "label": "Order date",
                    "name": "OrderDate",
                    "optional": false,
                    "parse_output": "date_conversion",
                    "render_input": "date_conversion",
                    "type": "date_time"
                }
            ],
            "description": "Triggered when a new order is placed."
        },
        {
            "id": 334526,
            "name": "Order shipped",
            "created_at": "2024-09-25T09:51:12.130-07:00",
            "updated_at": "2024-09-25T09:51:12.130-07:00",
            "retention": 604800,
            "schema": [
                {
                    "control_type": "text",
                    "label": "Order ID",
                    "name": "OrderId",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "text",
                    "label": "Shipping carrier",
                    "name": "ShippingCarrier",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "text",
                    "label": "Tracking number",
                    "name": "TrackingNumber",
                    "optional": false,
                    "type": "string"
                },
                {
                    "control_type": "date",
                    "label": "Shipped date",
                    "name": "ShippedDate",
                    "optional": false,
                    "parse_output": "date_conversion",
                    "render_input": "date_conversion",
                    "type": "date_time"
                }
            ],
            "description": "Triggered when an order is shipped."
        }
    ]
}

Create a topic

Creates a new event topic.

POST https://YOUR_DATA_CENTER/api/event_streams/topics

Name	Type	Description
name	string required	The name of the new topic.
schema	array required	The schema definition for the new topic. Must adhere to a valid Workato schema format.
schema[control_type]	string required	The control type for a field in the topic schema.
schema[label]	string required	The label that appears for the field in the topic schema.
schema[name]	string required	The name identifier for the field in the topic schema.
schema[optional]	boolean required	Specifies whether the field is optional.
schema[type]	string required	The data type of the field in the schema.
retention	number optional	Retention time for the topic in seconds. Defaults to 168 hours (604,800 seconds) if not specified.
description	string optional	A description of the new topic.

Sample request

This request creates a new event topic named Order delivered. The topic includes details such as the order ID, delivery date, and optional information about the person or service delivering the order.

shell

curl  -X POST "https://YOUR_DATA_CENTER/api/event_streams/topics" \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "name": ":name",
            "schema": [
                {
                    "control_type": ":control_type",
                    "label": ":label",
                    "name": ":schema_name",
                    "optional": :true_or_false,
                    "type": ":type"
                }
            ],
            "retention": :retention_value,
            "description": ":description"
         }'

Response

json

{
    "data": {
        "id": 334527,
        "name": "Order delivered",
        "created_at": "2024-09-25T09:56:32.986-07:00",
        "updated_at": "2024-09-25T09:56:32.986-07:00",
        "retention": 604800,
        "schema": [
            {
                "control_type": "text",
                "label": "Order ID",
                "name": "OrderId",
                "optional": false,
                "type": "string"
            },
            {
                "control_type": "date",
                "label": "Delivery date",
                "name": "DeliveryDate",
                "optional": false,
                "type": "date_time"
            },
            {
                "control_type": "text",
                "label": "Delivered by",
                "name": "DeliveredBy",
                "optional": true,
                "type": "string"
            }
        ],
        "description": "Triggered when an order is delivered."
    }
}

Get topic by ID

Retrieves an event topic by its ID.

GET https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id

URL parameters

Name	Type	Description
topic_id	number required	The ID of the event topic to retrieve.

Sample request

This request retrieves the Order delivered event topic by its unique :topic_id.

shell

curl  -X GET "https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id" \
      -H 'Authorization: Bearer <api_token>'

Response

json

{
    "data": {
        "id": 334527,
        "name": "Order delivered",
        "created_at": "2024-09-25T09:56:32.986-07:00",
        "updated_at": "2024-09-25T09:56:32.986-07:00",
        "retention": 604800,
        "schema": [
            {
                "control_type": "text",
                "label": "Order ID",
                "name": "OrderId",
                "optional": false,
                "type": "string"
            },
            {
                "control_type": "date",
                "label": "Delivery date",
                "name": "DeliveryDate",
                "optional": false,
                "type": "date_time"
            },
            {
                "control_type": "text",
                "label": "Delivered by",
                "name": "DeliveredBy",
                "optional": true,
                "type": "string"
            }
        ],
        "description": "Triggered when an order is delivered."
    }
}

Update a topic

Updates an event topic.

PUT https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id

URL parameters

Name	Type	Description
topic_id	number required	The ID of the event topic to update.

Name	Type	Description
name	string optional	The name of the updated topic.
schema	array optional	The schema definition for the updated topic. Must adhere to a valid Workato schema format.
schema[control_type]	string optional	The control type for a field in the topic schema.
schema[label]	string optional	The label that appears for the field in the topic schema.
schema[name]	string optional	The name identifier for the field in the topic schema.
schema[optional]	boolean optional	Specifies whether the field is optional.
schema[type]	string optional	The data type of the field in the schema.
retention	number optional	Retention time for the topic in seconds. Defaults to 168 hours (604,800 seconds) if not specified.
description	string optional	A description of the updated topic.

Sample request

This request updates the topic schema for the Order delivered event topic by adding a new field named Recipient.

shell

curl  -X PUT "https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id" \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "name": ":name",
            "schema": [
                {
                    "control_type": ":control_type",
                    "label": ":label",
                    "name": ":schema_name",
                    "optional": :true_or_false,
                    "type": ":type"
                }
            ],
            "retention": :retention_value,
            "description": ":description"
         }'

Response

json

{
    "data": {
        "id": 334527,
        "name": "Order delivered",
        "created_at": "2024-09-25T09:56:32.986-07:00",
        "updated_at": "2024-09-25T09:56:32.986-07:00",
        "retention": 604800,
        "schema": [
            {
                "control_type": "text",
                "label": "Order ID",
                "name": "OrderId",
                "optional": false,
                "type": "string"
            },
            {
                "control_type": "date",
                "label": "Delivery date",
                "name": "DeliveryDate",
                "optional": false,
                "type": "date_time"
            },
            {
                "control_type": "text",
                "label": "Delivered by",
                "name": "DeliveredBy",
                "optional": true,
                "type": "string"
            },
            {
                "control_type": "text",
                "label": "Recipient",
                "name": "Recipient",
                "optional": false,
                "type": "string"
            }
        ],
        "description": "Triggered when an order is delivered."
    }
}

Purge a topic

Erases all messages from the event topic's history and resets topic statistics.

PUT https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id/purge

Name	Type	Description
topic_id	string required	The ID of the event topic to purge.

Sample request

This request erases all messages from the Order delivered event topic's history and resets topic statistics.

shell

curl  -X PUT "https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id/purge" \
      -H 'Authorization: Bearer <api_token>'

Response

json

{
    "data": {
        "status": "success"
    }
}

Delete a topic

Deletes an event topic.

DELETE https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id

URL parameters

Name	Type	Description
topic_id	number required	The ID of the event topic to delete.

Sample request

This request deletes the Order delivered event topic.

shell

curl  -X DELETE "https://YOUR_DATA_CENTER/api/event_streams/topics/:topic_id" \
      -H 'Authorization: Bearer <api_token>'

Response

json

{
    "data": {
        "status": "success"
    }
}

Last updated:

Event streams ​

Public API ​

Developer API ​

Rate limits ​

Quick reference ​

List topics ​

Query parameters ​

Sample request ​

Response ​

Create a topic ​

Sample request ​

Response ​

Get topic by ID ​

URL parameters ​

Sample request ​

Response ​

Update a topic ​

URL parameters ​

Sample request ​

Response ​

Purge a topic ​

Sample request ​

Response ​

Delete a topic ​

URL parameters ​

Sample request ​

Response ​

Event streams

Public API

Developer API

Rate limits

Quick reference

List topics

Query parameters

Sample request

Response

Create a topic

Sample request

Response

Get topic by ID

URL parameters

Sample request

Response

Update a topic

URL parameters

Sample request

Response

Purge a topic

Sample request

Response

Delete a topic

URL parameters

Sample request

Response