Rivery API Overview

Introduction

This document provides a concise overview of the Rivery API, including authentication, token management, making API calls, and using the Activities API with Postman.

Authentication & API Tokens

Administrator Access

• Only account administrators (admin users) can manage API tokens.
• Admin users can add, view, and delete tokens.

Accessing Token Management

1. In the Rivery console, navigate to Settings → API Tokens.
2. View the list of existing tokens, which shows each token’s name, creation date, creator, and scopes.

Creating a Token

1. Click Add Token in the top-right.
2. Enter a token name (make it descriptive) and select the desired scopes (permissions).
   • You can expand each scope to read its description.
3. Click Create to generate the token (or Cancel to abort).
4. Copy the displayed token immediately—it cannot be viewed again later.
5. Click Done. The new token now appears in the list; click View to confirm its scopes.

Deleting a Token

1. Click the trash can icon beside the token you want to delete.
2. Confirm deletion in the popup.
   • Note: Once deleted, a token cannot be recovered or reused.

Plan Transition Notice:
When migrating from the Pro Plan to the Starter Plan, tokens remain active during a 14-day notice period. After 14 days, any leftover Pro Plan tokens will be automatically deleted.

Making API Calls

To invoke Rivery API endpoints:

• Include your API token as a Bearer token in the Authorization header.
• Use the correct base URL for your region:
  • US: https://console.rivery.io/api
  • EU: https://api.eu-west-1.rivery.io

Let's examine a practical illustration of how to use a River.

First, you will need to find the River ID.

This can be done by navigating to a specific River in the console and extracting the River ID from the URL:

In this case, the River id is: 63b724fc690def001131d242

Let's assume your token is: XYZ

This would be the specific curl in our example:

curl -X POST "https://console.rivery.io/api/run" 
-H "accept: application/json" 
-H "Authorization: Bearer XYZ" 
-H "Content-Type: application/json" 
-d "{ \"river_id\": \"63b724fc690def001131d242\"}"

The following describes the general curl:

curl -X POST "https://console.rivery.io/api/run" 
-H "accept: application/json" 
-H "Authorization: Bearer {token}" 
-H "Content-Type: application/json" 
-d "{ \"river_id\": \"{river_id}\"}"

Example: Running a River

1. Copy the River ID from the console URL (e.g., 63b724fc690def001131d242).

2. Use curl:

   curl -X POST "https://console.rivery.io/api/run" \
     -H "accept: application/json" \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{ "river_id": "63b724fc690def001131d242" }'
   
   

Python Example

import requests
import json

RIVER_ID = "1234567abcd"
url = "https://console.rivery.io/api/run"
payload = json.dumps({"river_id": RIVER_ID})
headers = {
    "accept": "application/json",
    "Authorization": f"Bearer {river_api_token}",
    "Content-Type": "application/json"
}

response = requests.post(url, data=payload, headers=headers)
print(response.json())

Activities API with Postman

The Data Integration Activities API requests can be easily explored through the use of the Postman Collection, a tool that allows for the examination of API endpoints without the need for writing a full-stack application. This collection offers pre-formatted requests for the Activities of Rivery's API endpoints, which can be accessed via the Postman desktop application or a web browser.

The Activities Postman Collection offers:

• Get statistics on the Environment's activity, including RPU (Units) consumption and run completion status.
• Get activity Targets (table names) for a specific River within a specified time frame and their current status.
• Get a list of run groups for a specific River within a specified time frame, including their completion status.
• Get a list of schedulers (aggregate runs) for a specific River within a specified time frame, including their completion status.
• Get a list of runs for a specific River within a specified time frame, including information on each run.
• Get a summary of Activities for the account and environment, grouped by a River.

Prerequisites

To use the Activities Postman Collection, it is necessary to have a Rivery account and a Postman.com account.

How Activities Postman Collection Work?

To begin, copy the Activites Postman Collection JSON and run in Postman to load the Activities API endpoint collection:

{
	"info": {
		"_postman_id": "d9880c37-8317-4dd7-9829-8dca4b60f78f",
		"name": "Rivery Activities API",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "16702673"
	},
	"item": [
		{
			"name": "Get Activities Statistic",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/activities_statistics?start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"activities_statistics"
					],
					"query": [
						{
							"key": "status",
							"value": "",
							"description": "Run status filter. Optinal values: \"pending\", \"canceled\", \"succeed\", \"failed\", and \"running\"",
							"disabled": true
						},
						{
							"key": "group_id",
							"value": "",
							"description": "The ID of the group to filter",
							"disabled": true
						},
						{
							"key": "is_scheduled",
							"value": "",
							"description": "A flag that indicates whether the river is scheduled. If not set then activities of all rivers will be returned (\"true\" / \"false\")\n",
							"disabled": true
						},
						{
							"key": "search",
							"value": "",
							"description": "Get statistics for rivers that has the search query in their name",
							"disabled": true
						},
						{
							"key": "river_type",
							"value": "",
							"description": "River type filter. Optinal values: \"src_to_trgt\", \"actions\", and \"logic\"",
							"disabled": true
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						}
					]
				},
				"description": "Get environment's activity statistics. The statistics include how many RPUs (Units) were consumed, and how many runs ended with each status."
			},
			"response": []
		},
		{
			"name": "Get River Activities Statistic",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/activities_statistics?start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"activities_statistics"
					],
					"query": [
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						},
						{
							"key": "status",
							"value": "",
							"description": "Run status filter. Optinal values: \"pending\", \"canceled\", \"succeed\", \"failed\", and \"running\"",
							"disabled": true
						}
					]
				},
				"description": "Get river's activity statistics (summary). The statistics include how many RPUs (Units) were consumed, and how many runs ended with each status"
			},
			"response": []
		},
		{
			"name": "Get River Activities Targets",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/activities_targets?start_time={{start_date}}&end_time={{end_date}}&scheduler_id",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"activities_targets"
					],
					"query": [
						{
							"key": "scheduler_id",
							"value": "",
							"description": "The aggregated run Id of multiple runs",
							"disabled": true
						},
						{
							"key": "sub_river_id",
							"value": "",
							"description": "The ID of the subriver",
							"disabled": true
						},
						{
							"key": "status",
							"value": "",
							"description": "Run status filter. Optinal values: \"pending\", \"canceled\", \"succeed\", \"failed\", and \"running\"",
							"disabled": true
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						},
						{
							"key": "scheduler_id",
							"value": null
						}
					]
				},
				"description": "Get river's activity targets (table names) in a specific time frame for specific river and their status. This endpoint should be used for multi table rivers."
			},
			"response": []
		},
		{
			"name": "Get River Activities Run Groups",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/activities_run_groups?page=1&items_per_page=200&start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"activities_run_groups"
					],
					"query": [
						{
							"key": "",
							"value": "",
							"disabled": true
						},
						{
							"key": "target_name",
							"value": "",
							"description": "Filter by target table name",
							"disabled": true
						},
						{
							"key": "sub_river_id",
							"value": "",
							"description": "Subriver river ID",
							"disabled": true
						},
						{
							"key": "status",
							"value": "",
							"description": "Run status filter. Only schedulers (aggregate runs) with these statuses will be returned.\nOptinal values: \"partially succeed\" \"pending\" \"canceled\" \"succeed\" \"failed\" \"running\"",
							"disabled": true
						},
						{
							"key": "sort_by",
							"value": "",
							"description": "Activities sort properties in the UI\nOptinal values:\"RPUs(Units)\", \"last_run\", and \"max_duration\" (Default: \"last_run\") ",
							"disabled": true
						},
						{
							"key": "sort_order",
							"value": "",
							"description": "The order of the results. Default: \"desc\"\noptinal values: \"desc\", and \"asc\"\n",
							"disabled": true
						},
						{
							"key": "page",
							"value": "1",
							"description": "Default: 1"
						},
						{
							"key": "items_per_page",
							"value": "200",
							"description": "Default: 50, Range: [ 1 .. 200 ]"
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						}
					]
				},
				"description": "**Get list of run groups that occurred in a specific time** **frame for specific river and their status.**"
			},
			"response": []
		},
		{
			"name": "Get River Activities Sub Rivers",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/activities_sub_rivers?start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"activities_sub_rivers"
					],
					"query": [
						{
							"key": "target_name",
							"value": "",
							"description": "Filter by target table name",
							"disabled": true
						},
						{
							"key": "scheduler_id",
							"value": "",
							"description": "The aggregated run Id of multiple runs",
							"disabled": true
						},
						{
							"key": "",
							"value": "",
							"disabled": true
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						}
					]
				},
				"description": "Get list of schedulers (aggregate runs) that occurred in a specific time frame for specific river and their status."
			},
			"response": []
		},
		{
			"name": "Get River Activities Runs",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/runs?page=1&items_per_page=200&start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"runs"
					],
					"query": [
						{
							"key": "target_name",
							"value": "",
							"description": "Filter by target table name",
							"disabled": true
						},
						{
							"key": "scheduler_id",
							"value": "",
							"description": "The aggregated run Id of multiple runs",
							"disabled": true
						},
						{
							"key": "sub_river_id",
							"value": "",
							"description": "The ID of the subriver",
							"disabled": true
						},
						{
							"key": "page",
							"value": "1",
							"description": "Default: 1"
						},
						{
							"key": "items_per_page",
							"value": "200",
							"description": "Default: 50, Range: [ 1 .. 200 ]"
						},
						{
							"key": "",
							"value": "",
							"disabled": true
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						}
					]
				},
				"description": "Get list of runs for a specific river in a specific time frame. This endpoint return information about each of the runs."
			},
			"response": []
		},
		{
			"name": "Get River Activities Run",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/rivers/{{river_id}}/runs/{{run_id}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"rivers",
						"{{river_id}}",
						"runs",
						"{{run_id}}"
					]
				},
				"description": "Get specific run details"
			},
			"response": []
		},
		{
			"name": "Get Activities",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{base-url}}/v1/accounts/{{account_id}}/environments/{{environment_id}}/activities?start_time={{start_date}}&end_time={{end_date}}",
					"host": [
						"{{base-url}}"
					],
					"path": [
						"v1",
						"accounts",
						"{{account_id}}",
						"environments",
						"{{environment_id}}",
						"activities"
					],
					"query": [
						{
							"key": "status",
							"value": "",
							"description": "Run status filter. Optinal values: \"pending\", \"canceled\", \"succeed\", \"failed\", and \"running\"\n",
							"disabled": true
						},
						{
							"key": "group_id",
							"value": "",
							"description": "The ID of the river group to filter",
							"disabled": true
						},
						{
							"key": "is_scheduled",
							"value": "",
							"description": "A flag that indicates whether the river is scheduled. If not set then activities of all rivers will be returned (\"true\" / \"false\")",
							"disabled": true
						},
						{
							"key": "page",
							"value": "",
							"description": "Default: 1",
							"disabled": true
						},
						{
							"key": "items_per_page",
							"value": "",
							"description": "Default: 50, Range: [ 1 .. 200 ]",
							"disabled": true
						},
						{
							"key": "return_last_runs",
							"value": "",
							"description": "Returns only the last run for each of the runs. (boolean), Defult: false",
							"disabled": true
						},
						{
							"key": "search",
							"value": "",
							"description": "Search for a specific river by river name",
							"disabled": true
						},
						{
							"key": "sort_by",
							"value": "",
							"description": "Activities sort properties in the UI.\nOptinal values:\"RPUs(Units)\", \"last_run\", and \"max_duration\" (Default: \"last_run\") ",
							"disabled": true
						},
						{
							"key": "sort_order",
							"value": "",
							"description": "The order of the results. Default: \"desc\"\noptinal values: \"desc\", and \"asc\"\n",
							"disabled": true
						},
						{
							"key": "river_type",
							"value": "",
							"description": "River type filter. Optinal values: \"src_to_trgt\", \"actions\", and \"logic\"",
							"disabled": true
						},
						{
							"key": "start_time",
							"value": "{{start_date}}"
						},
						{
							"key": "end_time",
							"value": "{{end_date}}"
						}
					]
				},
				"description": "Get summary of activities for the account and environment summarized by river."
			},
			"response": []
		}
	],
	"auth": {
		"type": "bearer",
		"bearer": [
			{
				"key": "token",
				"value": "<your_access_token>",
				"type": "string"
			}
		]
	},
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"key": "account_id",
			"value": "<your_account_id>",
			"type": "string"
		},
		{
			"key": "environment_id",
			"value": "<your_environment_id>"
		},
		{
			"key": "river_id",
			"value": "<your_river_id>"
		},
		{
			"key": "run_id",
			"value": "<your_river_run_id>"
		},
		{
			"key": "base-url",
			"value": "<For US console use: https://api.rivery.io >\n<For EU console use: \nhttps://api.eu-west-1.rivery.io >",
			"type": "string"
		},
		{
			"key": "start_date",
			"value": "<yyyy-mm-ddThh:mm:ss>",
			"type": "string"
		},
		{
			"key": "end_date",
			"value": "<yyyy-mm-ddThh:mm:ss>",
			"type": "string"
		}
	]
}

Once the collection is loaded, API Tokens and arguments will need to be filled in to use the requests in the collection.

Consult our guide to create and use API Tokens.

Here's how to locate the necessary arguments, select a particular River in the Rivery console, and pull the IDs from the URL:

Please Note:
The slash character (/) should not be included when copying the arguments from the URL.