# 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 were migrated to the https://event-streams.workato.com 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.
Note: Legacy endpoints published on https://www.workato.com/api (under the /pubsub/topics/ namespace) still function but are rate-limited to 1,000 requests per minute.
# Developer API
The following endpoints use the https://www.workato.com domain:
- 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
# 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 /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.
curl -X GET "https://www.workato.com/api/event_streams/topics?name=Order&sort=id&include_schema=true" \
-H 'Authorization: Bearer <api_token>'
# Response
{
"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 /api/event_streams/topics
# Payload
| 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.
curl -X POST "https://www.workato.com/api/event_streams/topics" \
-H 'Authorization: Bearer <api_token>' \
-H "Content-Type: application/json" \
-d '{
"name": "Order delivered",
"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."
}'
# Response
{
"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 /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 ID (334527).
curl -X GET "https://www.workato.com/api/event_streams/topics/334527" \
-H 'Authorization: Bearer <api_token>'
# Response
{
"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 /api/event_streams/topics/:topic_id
# URL parameters
| Name | Type | Description |
|---|---|---|
| topic_id | number required | The ID of the event topic to update. |
# Payload
| 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.
curl -X PUT "https://www.workato.com/api/event_streams/topics/334527" \
-H 'Authorization: Bearer <api_token>' \
-H "Content-Type: application/json" \
-d '{
"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"
}
]
}'
# Response
{
"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 /api/event_streams/topics/:topic_id/purge
# Payload
| 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.
curl -X PUT "https://www.workato.com/api/event_streams/topics/334527/purge" \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": {
"status": "success"
}
}
# Delete a topic
Deletes an event topic.
DELETE /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.
curl -X DELETE "https://www.workato.com/api/event_streams/topics/334527" \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": {
"status": "success"
}
}
Last updated: 10/16/2024, 3:02:32 PM