API docs by Redocly

Timeplus (v1)

Download OpenAPI specification:Download

API Support: support@timeplus.com URL: https://timeplus.com

Welcome to the Timeplus HTTP REST API specification.

Alerts v1beta2

list alerts

Get all alerts.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an alert

Create an alert. Please refer to the documentation of alert for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create alert request parameters

action
required
string

Sink template - the following properties are used to create the sink One action can be map to a sink

description
string
name
required
string
object

Detailed properties to create the sink

resolve_sql
string
severity
required
integer
trigger_sql
required
string

Persistent query template - the following properties are used to create the persistent query

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "description": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "trigger_sql": "string"
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

delete an alert

Delete the alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an alert

Get an alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

update an alert

Update the specific alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Request Body schema: application/json
required

update alert request parameters

action
required
string

Sink template - the following properties are used to create the sink One action can be map to a sink

description
string
name
required
string
object

Detailed properties to create the sink

resolve_sql
string
severity
required
integer
trigger_sql
required
string

Persistent query template - the following properties are used to create the persistent query

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "description": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "trigger_sql": "string"
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

resolve a triggered alert

Manually resolve a triggered alert so that it can be triggered again by the trigger event in the future.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

start an alert

Start the alert with the given ID. If the alert is already running, the API does nothing and returns 204.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

stop an alert

Stop the alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

API keys v1beta2

list API keys

Get all API keys created by current user

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an API key

Create a new API key with optional expiration, the created API key represents the owner thus has the same permissions as the owner

Authorizations:
ApiKeyAuth
Request Body schema: application/json

API Key parameters

expire_at
string <RFC3339>

define the expiration time of the API key by specifying the exact date time, cannot use with expire_in

expire_in
string

define the expiration time of the API key by specifying the amount of time to count from now, cannot use with expire_at

name
string

the name of the API key.

  • If name is speicfied, the masked API key will be appended to the end of the name (e.g. myAPIKey (vthm****OjXG)).
  • If name is not speicfied, the masked API key will be used as the name (e.g. vthm****OjXG).

Responses

Request samples

Content type
application/json
{
  • "expire_at": "2022-06-07T12:00:00Z08:00",
  • "expire_in": "24h",
  • "name": "myAPIKey"
}

Response samples

Content type
application/json
{
  • "api_key": "vthm5o5ENm4TaX5RcixG+DB8q9ALQtrU3VlfQBVFv1lQauWeDXR87MI5kOjXG",
  • "created_at": 1257894000,
  • "expire_at": 1257894000,
  • "id": "string",
  • "name": "myAPIKey (vthm****OjXG)",
  • "permissions": [
    ]
}

delete an API key

Delete the API key with the givin ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

API key ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Dashboards v1beta2

list dashboards

Get all dashboards.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a dashboard

Create a dashboard.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

dashboard request parameters

description
string
name
required
string
Array of objects (dashboard.Panel)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "panels": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

delete a dashboard

Delete the dashboard with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a dashboard

get a dashboard.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

update a dashboard

Update the specific dashboard with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Request Body schema: application/json
required

update dashboard request parameters

description
string
name
required
string
Array of objects (dashboard.Panel)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "panels": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

Queries v1beta2

format a query

Format the given query and make it easy to read.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

the query SQL to be formatted

sql
string

Responses

Request samples

Content type
application/json
{
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "sql": "string"
}

list queries

Get all queries.

Authorizations:
ApiKeyAuth
query Parameters
tag
string

filter by tag

Responses

Response samples

Content type
application/json
[
  • {
    }
]

execute a query and return the results

Execute a query and return the results.

  • If the request fails, the response content type will be application/json. Please refer to the failure codes in Responses section below.
  • If the query is executed successfully, the response content type will be text/event-stream. For SSE There are 3 types of data that will be sent to SSE channel
  1. Query (type query): The first event of the result will ALWAYS be this type.
  2. Metrics (type metrics): The query metrics in JSON. They will be sent every 1 seconds.
  3. Data (the type is empty): The query result.
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

query request parameters

object (BatchingPolicy)
description
string
name
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "batching_policy": {
    },
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
{
  • "analysis": {
    },
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "ad-hoc streaming query",
  • "duration": 10,
  • "end_time": 1689809152,
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "test_query",
  • "response_time": 1,
  • "result": {
    },
  • "sinks": {
    },
  • "sql": "select * from iot",
  • "start_time": 1689809142,
  • "status": "running",
  • "tags": [
    ],
  • "timeColumns": {
    }
}

delete a query

Delete the query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a query

Get the query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "ad-hoc streaming query",
  • "duration": 10,
  • "end_time": 1689809152,
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "test_query",
  • "response_time": 1,
  • "result": {
    },
  • "sinks": {
    },
  • "sql": "select * from iot",
  • "start_time": 1689809142,
  • "status": "running",
  • "tags": [
    ],
  • "timeColumns": {
    }
}

cancel a query

Cancel the query with the given ID. If given query is not running, the request will do nothing. Otherwise, the query will be canceled and the status will be set to canceled

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the pipeline for a query

get the pipeline for a query

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "nodes": [
    ]
}

execute a DDL query

Execute a DDL query. Currently only create external stream is supported.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

query request parameters

sql
required
string

Responses

Request samples

Content type
application/json
{
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "ad-hoc streaming query",
  • "duration": 10,
  • "end_time": 1689809152,
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "test_query",
  • "response_time": 1,
  • "result": {
    },
  • "sinks": {
    },
  • "sql": "select * from iot",
  • "start_time": 1689809142,
  • "status": "running",
  • "tags": [
    ],
  • "timeColumns": {
    }
}

analyze sql

analyze sql

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

sql request parameters

sql
string

Responses

Request samples

Content type
application/json
{
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "group_by_columns": [
    ],
  • "has_aggr": true,
  • "has_subquery": true,
  • "has_table_join": true,
  • "has_union": true,
  • "is_streaming": true,
  • "original_query": "string",
  • "query_type": "string",
  • "required_columns": [
    ],
  • "result_columns": [
    ],
  • "rewritten_query": "string"
}

Metrics v1beta2

query global metrics

query global metrics.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "sink_throughput": 0,
  • "source_throughput": 0,
  • "storage": 0
}

Invitations v1beta2

list invitations

Get all invitations.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an invitation

Invite an user to the current tenant.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create invitation request parameters

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

delete an invitation

Delete the invitation with the given ID. Deleting the invitation will remove the user from current workspace.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

invitation ID

Responses

Saved queries v1beta2

list Saved queries

Get all saved queries

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an saved query

Create a new saved query.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

saved query parameters

description
string
name
required
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

delete a saved query

Delete the saved query with the givin ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a saved query

Get a saved query.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

update a saved query

Update the specific saved query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Request Body schema: application/json
required

update saved query request parameters

description
string
name
required
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

Sinks v1beta2

list sinks

Get all sinks

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a sink

Create a sink. Please refer to the documentation of sink for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create sink request parameters

description
string
name
required
string

Sink name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to write the data to the sink (e.g. broker url). Please refer to the documentation for this sink type

query
required
string
type
required
string

Available types: [slack, http, kafka, redpanda, confluent_cloud, pulsar, timeplus]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "write data to kafka",
  • "name": "write_to_kafka",
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "type": "kafka"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to kafka",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_kafka",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "kafka"
}

delete a sink

Delete a sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a sink

Get a sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to kafka",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_kafka",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "kafka"
}

update a sink

Update the specific sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Request Body schema: application/json
required

update sink request parameters

description
string
name
required
string

Sink name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to write the data to the sink (e.g. broker url). Please refer to the documentation for this sink type

query
required
string
type
required
string

Available types: [slack, http, kafka, redpanda, confluent_cloud, pulsar, timeplus]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "write data to kafka",
  • "name": "write_to_kafka",
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "type": "kafka"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to kafka",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_kafka",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "kafka"
}

start a sink

Start the sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a sink

Get the stats of a sink with the given id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

query Parameters
error_log_time_range
required
string
Example: error_log_time_range=1d
metrics_time_range
required
string
Example: metrics_time_range=10m

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "errors": [
    ],
  • "failure_count": 1,
  • "historical_data_bytes": 234567,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "success_count": 99,
  • "throughput": [
    ]
}

stop a sink

Stop the sink with the given ID from sending out data.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Sources v1beta2

preview a source

Get sample events from the source with the given ID. Please refer to create source for more details regarding type and properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

source propeties for preview

object

See CreateSourceRequest

size
integer

Number of preview events, works together with Timeout.

timeout
string

Indicates how long should preview last to fetch the desired amount of data indicated by size A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

type
required
string

See CreateSourceRequest

Responses

Request samples

Content type
application/json
{
  • "properties": {
    },
  • "size": 1,
  • "timeout": "1m",
  • "type": "kafka"
}

Response samples

Content type
application/json
[
  • {
    }
]

list sources

Get all sources.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a source

Create a source. Please refer to the documentation of source for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create source request parameters

description
string
name
required
string

Source name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to read the data from source (e.g. broker url). Please refer to the documentation for this source type

stream
required
string

The name of the target stream that this source writes to. The stream needs to be created first.

type
required
string

Available types: [ably, stream_generator, kafka, redpanda, confluent_cloud, pulsar, websocket, nats, nats_jetstream]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "read from my kafka topic",
  • "name": "my_kafka_source",
  • "properties": {
    },
  • "stream": "kafak_stream",
  • "type": "kafka"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from my kafka topic",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_kafka_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "kafka_stream",
  • "type": "kafka"
}

delete a source

Delete the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a source

Get a source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from my kafka topic",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_kafka_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "kafka_stream",
  • "type": "kafka"
}

update a source

Update the specific source with the given ID. Only stopped sources can be updated.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Request Body schema: application/json
required

update source request parameters

description
string
name
string

Source name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to read the data from source (e.g. broker url). Please refer to the documentation for this source type

stream
string

The name of the target stream that this source writes to. The stream needs to be created first.

Responses

Request samples

Content type
application/json
{
  • "description": "new description for the source",
  • "name": "new_source_name",
  • "properties": {
    },
  • "stream": "new_stream"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from my kafka topic",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_kafka_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "kafka_stream",
  • "type": "kafka"
}

start a source

Start the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a source

Get the stats of a source with the given id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

query Parameters
error_log_time_range
required
string
Example: error_log_time_range=1d
metrics_time_range
required
string
Example: metrics_time_range=10m

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "failure_count": 1,
  • "success_count": 99,
  • "throughput": [
    ]
}

stop a source

Stop the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Streams v1beta2

list streams

Get all streams.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a stream

Create a stream. Please refer to the documentation of stream for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create stream request parameters

Array of objects (ColumnDef)
description
string
event_time_column
string

This column will be used as the event time if specified

event_time_timezone
string

The timezone of the TimestampColumn

logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

mode
string
Enum: "append" "changelog" "changelog_kv" "versioned_kv"

Storage mode of stream. Defaulted to append.

name
required
string

Stream name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

order_by_expression
string
order_by_granularity
string
partition_by_granularity
string
primary_key
string

Expression of primary key, required in changelog_kv and versioned_kv mode

replication_factor
integer
shards
integer
ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ],
  • "description": "my first stream",
  • "event_time_column": "time",
  • "event_time_timezone": "UTC",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "mode": "append",
  • "name": "test_stream",
  • "order_by_expression": "string",
  • "order_by_granularity": "string",
  • "partition_by_granularity": "string",
  • "primary_key": "string",
  • "replication_factor": 0,
  • "shards": 0,
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "engine": "Stream",
  • "is_external": false,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 1073741824,
  • "logstore_retention_ms": 86400000,
  • "mode": "append",
  • "name": "test_stream",
  • "primary_key": "string",
  • "settings": [
    ],
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

delete a stream

Delete the stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a stream

Get a stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "engine": "Stream",
  • "is_external": false,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 1073741824,
  • "logstore_retention_ms": 86400000,
  • "mode": "append",
  • "name": "test_stream",
  • "primary_key": "string",
  • "settings": [
    ],
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

update a stream

Update the specific stream with the given name. Right now it only supports updating data retention-related settings. Altering stream or updating external stream is not supported yet.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

name of the stream

Request Body schema: application/json
required

update stream request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "new description",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

ingest data

Ingest data to a stream with the given name. For formats are supported:

  • compact JSON: when Content-Type is set to one of application/json, application/json;format=compact, application/vnd.timeplus+json, application/vnd.timeplus+json;format=compat, or set format query parameter with value compact. And this is the API's default format.
  • JSON stream: when Content-Type is set to one of application/json;format=streaming, application/vnd.timeplus+json;format=streaming, or set format query parameter with value streaming.
  • raw string: when Content-Type is set to one of text/plain, text/plain;format=raw, or set format query parameter with value raw.
  • string lines: when Content-Type is set to text/plain;format=lines, or set format query parameter with value lines.
  • refer to https://docs.timeplus.com/docs/ingest-api for more information *
Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

query Parameters
format
string
Enum: "compact" "streaming" "raw" "lines"

enfoce payload format, if it is set, it overwrite the Content-Type header

Request Body schema:
required

ingest data

columns
required
Array of strings
data
required
Array of any[ items ]

Responses

Request samples

Content type
{
  • "columns": [
    ],
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a stream

Get the stats of a stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "row_count": 20,
  • "streaming_data_bytes": 12345
}

create an external stream

Create an external stream.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create external stream request parameters

description
string
name
required
string
Array of objects (StreamSetting)

Responses

Request samples

Content type
application/json
{
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

Subscription v1beta2

get current subscription

Get the status of current subscription.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "cpu": 1000,
  • "customer": {
    },
  • "payment": {
    },
  • "storage_size": 10737418240,
  • "subscription_plan": "Free Trial"
}

Topology v1beta2

get topology graph

Get topology graph of all existings resources.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "nodes": [
    ]
}

UDFs v1beta2

list user-defined functions

Get all user-defined functions.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an user-defined function

Create an user-defined function.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create UDF request parameters

Array of objects (UDFArgument)

The input argument of the UDF

  • For UDA: the number and type of arguments should be consistent with the main function of UDA. the type should be the data types of proton not javascript types. It only supports int8/16/32/64, uint8/16/32/64,
object (UDFAuthContext)
auth_method
string

Only valid when type is remote. This field is used to set the authentication method for remote UDF. It can be either auth_header or none. When auth_header is set, you can configure auth_context to specify the HTTP header that be sent the remote URL

created_at
string
object (Owner)
description
string
is_aggregation
boolean

Only valid when type is 'javascript'. Whether it is an aggregation function.

last_updated_at
string
object (Owner)
name
required
string
return_type
string

The erturn type of the UDF

  • For UDA: if it returns a single value, the return type is the corresponding data type of Timeplus. It supports the same types of input arguments, except for datetime, it only supports DateTime64(3).
source
string

Only valid when type is 'javascript' The source code of the UDA. There are functions to be defined:

  • main function: with the same name as UDA. Timeplus calls this function for each input row. The main function can return two types of result: object or simple data type
    • If it returns an object, the object is like {“emit”: true, “result”: …}. ‘Emit’ (boolean) property tells Timeplus whether or not the result should emit. ‘result’ is the current aggregate result, if ‘emit’ is false, the result will be ignored by Timeplus. Timeplus will convert the ‘result’ property of v8 to the data types defined when creating UDA.
    • If it returns a simple data type, Timeplus considers the return data as the result to be emitted immediately. It converts the return data to the corresponding data type and Timeplus emits the aggregating result.
    • Once UDA tells Timeplus to emit the data, UDA takes the full responsibility to clear the internal state, prepare and restart a new aggregating window, et al.
  • state function: which returns the serialized state of all internal states of UDA in string. The UDA takes the responsibility therefore Timeplus can choose to persist the internal state of UDA for query recovery.
  • init function: the input of this function is the string of serialized state of the internal states UDA. Timeplus calls this function when it wants to recover the aggregation function with the persisted internal state.
type
required
string

Either javascript or remote

url
string

Only valid when type is remote.

Responses

Request samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

delete an user-defined function

Delete the user-defined function with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

user-defined function name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an user-defined function

get the user-defined function with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

user-defined function name

Responses

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

update an user-defined function

Update the specific user-defined function with the given name.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update UDF request parameters

Array of objects (UDFArgument)

The input argument of the UDF

  • For UDA: the number and type of arguments should be consistent with the main function of UDA. the type should be the data types of proton not javascript types. It only supports int8/16/32/64, uint8/16/32/64,
object (UDFAuthContext)
auth_method
string

Only valid when type is remote. This field is used to set the authentication method for remote UDF. It can be either auth_header or none. When auth_header is set, you can configure auth_context to specify the HTTP header that be sent the remote URL

created_at
string
object (Owner)
description
string
is_aggregation
boolean

Only valid when type is 'javascript'. Whether it is an aggregation function.

last_updated_at
string
object (Owner)
name
required
string
return_type
string

The erturn type of the UDF

  • For UDA: if it returns a single value, the return type is the corresponding data type of Timeplus. It supports the same types of input arguments, except for datetime, it only supports DateTime64(3).
source
string

Only valid when type is 'javascript' The source code of the UDA. There are functions to be defined:

  • main function: with the same name as UDA. Timeplus calls this function for each input row. The main function can return two types of result: object or simple data type
    • If it returns an object, the object is like {“emit”: true, “result”: …}. ‘Emit’ (boolean) property tells Timeplus whether or not the result should emit. ‘result’ is the current aggregate result, if ‘emit’ is false, the result will be ignored by Timeplus. Timeplus will convert the ‘result’ property of v8 to the data types defined when creating UDA.
    • If it returns a simple data type, Timeplus considers the return data as the result to be emitted immediately. It converts the return data to the corresponding data type and Timeplus emits the aggregating result.
    • Once UDA tells Timeplus to emit the data, UDA takes the full responsibility to clear the internal state, prepare and restart a new aggregating window, et al.
  • state function: which returns the serialized state of all internal states of UDA in string. The UDA takes the responsibility therefore Timeplus can choose to persist the internal state of UDA for query recovery.
  • init function: the input of this function is the string of serialized state of the internal states UDA. Timeplus calls this function when it wants to recover the aggregation function with the persisted internal state.
type
required
string

Either javascript or remote

url
string

Only valid when type is remote.

Responses

Request samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Views v1beta2

list views

Get all views.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a view

Create a view. There are two different types of the view, please refer to the documentation of view for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create view request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

materialized
boolean
Default: false
name
required
string

View name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

query
required
string
target_stream
string

This option is applicable only when materialized is true. Specify this when you want to have multiple materialized views sink to the same target stream.

ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "the description of my_test_view",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_test_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

delete a view

Delete the view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a view

Get a view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

update a view

Update the specific view with the given name. Updating the query of a materialized view is not allowed

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

name of the view

Request Body schema: application/json
required

update view request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

query
string
ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "query": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a view

Get the stats of a view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "row_count": 20,
  • "streaming_data_bytes": 12345
}

Workspace v1beta2

get current workspace

Get the basic information about the current workspace.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "demo_mode": false,
  • "enabled_subscription": true,
  • "free_trial_end_date": "2023-02-13T07:08:09.012Z",
  • "id": "t5abcd1e",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "my_workspace",
  • "settings": {
    }
}

update current workspace

Update the settings of current workspace

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update workspace request parameters

object (WorkspaceSettings)

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}