Postman is a popular developer tool for building and testing various types of API calls. With the Rivery postman collection, we have created pre-configured API requests for all Rivery API endpoints.
In order to use the collection:
-
Create an API token with the appropriate scopes for the endpoints that you are trying to test by logging into the Rivery console as an admin, navigating to the “API Tokens” tab and clicking “Add Token”. Save the token somewhere safe.
-
Download the attached json file and at the very bottom, set the value of the variable “access token” with the API token that you created in Step (1).
-
Save the json file and in Postman, navigate to your workspace and click “Import”
. Browse for the file that you saved in step (2) and upload it. -
The Collection should now be visible in your UI and you should be able to make API calls with the pre-configured endpoints! Make sure to set any variables in the API calls that have placeholder {{variables}} with appropriate values.
Collection:
{
"info": {
"_postman_id": "2ac4028e-1d8a-40ee-947f-15b05ff9dd28",
"name": "Rivery API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Connections",
"item": [
{
"name": "Connection Types and Properties",
"item": [
{
"name": "Connection Types List",
"request": {
"method": "GET",
"header": [],
"url": null,
"description": "All of the available connection types in Rivery."
},
"response": []
},
{
"name": "Connection Type Properties",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/connections/properties/{{connectionTypeId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"properties",
"{{connectionTypeId}}"
]
},
"description": "List all properties of all connection types available in Rivery."
},
"response": []
}
]
},
{
"name": "Connection Management",
"item": [
{
"name": "List all Connections",
"request": {
"method": "GET",
"header": [],
"url": null,
"description": "List all connections and their details in the Rivery account."
},
"response": []
},
{
"name": "Filter Connections by Connection Type",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/connections/{{connectionTypeId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"{{connectionTypeId}}"
],
"query": [
{
"key": "cross_id",
"value": "",
"disabled": true
}
]
},
"description": "List all connections filtering by the connection type."
},
"response": []
},
{
"name": "Create New Connection",
"request": {
"method": "PUT",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n\"connection_type\": \"aws\",\n\"connection_name\": \"My S3 Connection\",\n\"aws_access_key\": \"smd0mLSCJHodKndas\",\n\"aws_access_secrets\": \"Amndsjkjns0nmnre3.nkdskndYkHDS\",\n\"connection_method\": \"aws_keys\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/connections",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections"
]
},
"description": "Create a new connection in the Rivery account. See the documentation for PUT example body's for connections requiring OAuth2.0 or Pem files: https://riveryio.github.io/rivery-api-docs/#operation/CreateConnection"
},
"response": []
},
{
"name": "Get Specific Connection",
"request": {
"method": "GET",
"header": [],
"url": null,
"description": "Get specific connection details by specifying that connections connection_id (available by hitting the \"List all Connections\" endpoint)."
},
"response": []
},
{
"name": "Update Connection by ID",
"request": {
"method": "PATCH",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n\"connection_type\": \"aws\",\n\"connection_name\": \"My S3 Connection\",\n\"aws_access_key\": \"smd0mLSCJHodKndas\",\n\"aws_access_secrets\": \"Amndsjkjns0nmnre3.nkdskndYkHDS\",\n\"connection_method\": \"aws_keys\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/connections/{{connectionId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"{{connectionId}}"
]
},
"description": "Create New Connection using the connection name, connection type, and connection parameters as described in connection parameters API request."
},
"response": []
},
{
"name": "Delete Connection by ID",
"request": {
"method": "DELETE",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/connections/{{connectionId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"{{connectionId}}"
]
},
"description": "Delete the connection specified by the connection_id."
},
"response": []
}
]
},
{
"name": "Connection Key Files",
"item": [
{
"name": "Create Connection Key FIle",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/connections/{{connectionTypeId}}/file",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"{{connectionTypeId}}",
"file"
]
},
"description": "Upload and creating new key file in the system. Key file is required for some connections keys, when the connection type property type value in file. Use the key_file_name from the returned JSON and attach it to the correct key in connection."
},
"response": []
}
],
"description": "Uploading and Creating new files for connections, in cases of certificate files or encrypted files needed. For example, when connecting the Google Cloud Platform (GCP) resources (BigQuery and GCS), there's a need to provide a *.json file; In SSH Tunnel, a *.pem file is also needed in most cases."
},
{
"name": "OAuth2.0 Connections",
"item": [
{
"name": "OAuth2 New Credentials Request",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n\"datasource_id\": \"fb\",\n\"validity_duration\": 300\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/oauth2",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"oauth2"
]
},
"description": "Initiating new OAuth2 process using Rivery.\nThe request will provide an external link of auth_uri, that can be hit externally to the API (using any web browser). After the process will end in the provider side, Rivery will get a callback request from the OAuth2 provider, and Rivery will continue the process.\nIn order to get the OAuth2 process response, please continue to /oauth2/credentials.\n\nResponse will include auth_uri and pull_id to provide to /oauth2/credentials request."
},
"response": []
},
{
"name": "OAuth2 Get Credentials",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n\"pull_id\": \"eyJhbGciOiJIUzI1NiIsImV4cCI6MTUwMjM3OTk3NywiaWF0IjoxNTAyMzc5Mz....\",\n\"auth_uri\": \"https://login.windows.net/...\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/oauth2/credentials",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"oauth2",
"credentials"
]
},
"description": "Getting the results of the Oauth2 process request."
},
"response": []
}
],
"description": "Oauth2 process initiation. In order to support OAuth2 connections, In order to create new connections OAuth2 method, there's a need to create OAuth2 request to the provider, and then get the credentials by callback. The OAuth2 response will provide a credentials response that will be pass to the connection used an OAuth2 request in the credentials key. In order to determine the OAuth2 connections in Rivery, find the oauth=true segmentation in the connection type."
},
{
"name": "Share Connection",
"item": [
{
"name": "Get Connection Creation Shareable Link",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/connections/share_creation_link/{{datasourceTypeId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"connections",
"share_creation_link",
"{{datasourceTypeId}}"
]
},
"description": "Rivery provides the ability to get a shareable link, that will open a connection modal (html) which can be shared with 3rd parties (like customers) in order to create a new connection inside Rivery. The link is one-time only, and expires after 24 hours at most."
},
"response": []
}
]
}
]
},
{
"name": "Rivers Management",
"item": [
{
"name": "Get River",
"item": [
{
"name": "Get Rivers List",
"request": {
"method": "GET",
"header": [],
"url": null,
"description": "Get a list of all rivers in the Rivery account-environment that the created token lives in."
},
"response": []
}
]
},
{
"name": "Sub Rivers Properties",
"item": [
{
"name": "Get Sub Rivers Properties by Datasource ID",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/properties/subrivers?datasource_id=",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"properties",
"subrivers"
],
"query": [
{
"key": "datasource_id",
"value": ""
}
]
},
"description": "Get Sub Rivers Properties by Datasource ID. Example: datasource_id=klaviyo."
},
"response": []
},
{
"name": "Get Sub Rivers Properties by River ID",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/properties",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"properties"
]
},
"description": "Get Sub Rivers Properties by River ID. This method checks the source and target config of the main river and returns the properties of every subriver."
},
"response": []
}
]
},
{
"name": "Sub Rivers Columns",
"item": [
{
"name": "Get sub rivers columns headers by River",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers/columns",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers",
"columns"
]
},
"description": "Returns the sub-river valid column headers that can be provided to the sub-rivers of the main river (defined by the river_id)."
},
"response": []
},
{
"name": "Change the Sub River column headers in River",
"request": {
"method": "PATCH",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n\"key\": \"target_table\",\n\"scope\": \"source\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers/columns",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers",
"columns"
]
},
"description": "Create/Delete/Update order of sub river columns in specific riverId."
},
"response": []
}
],
"description": "In order to manage sub rivers inside a river, there is a need to set first the column subset defined in each river for its sub rivers. That means, every sub river that is created/updated is compared to the valid sub river columns defined in the river.\n\nIf a sub river has more columns than the sub river columns defined, an error is raised. The list of the sub river valid columns for each datasource_type or river is based on the Sub River Properties request.\n\nSub rivers are based on the columns chosen in the the main sub rivers tables. Sub rivers table is composed of global columns per river, and a full or partial row of values by each sub river to fill. Every sub river values are validated by the data type, and the correct values that can be inserted to each column.\n\nFor example:\nIn a parent klaviyo river, we can define columns from the list returned in Sub River Properties requests, and then set the right subset of columns in every river we want to use."
},
{
"name": "Sub Rivers Management",
"item": [
{
"name": "Get all sub rivers per river",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers"
]
},
"description": "Get all sub rivers associated with a specific river_id."
},
"response": []
},
{
"name": "Create new sub river(s) for river",
"request": {
"method": "PUT",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n\"sub_rivers\": [\n{\n\"name\": \"My Subriver\",\n\"description\": \"My Facebook clients sub river\",\n\"source\": {\n\"date_range\": {\n\"start_date\": \"2020-10-10T12:23:34.123Z\",\n\"end_date\": \"2020-10-11T12:34:45.123Z\",\n\"days_back\": 5,\n\"time_period\": \"custom\"\n},\n\"report\": \"campaigns\",\n\"connection_id\": \"5fa7c995f5as82c6crfb9dd565\"\n},\n\"target\": {\n\"table_name\": \"ods_klaviyo_campaigns\",\n\"schema_name\": \"public\"\n},\n\"is_scheduled\": true,\n\"schedule\": {\n\"cron\": \"* 15 1/2 * * *\"\n},\n\"inherit_schedule\": true,\n\"is_enabled\": false\n}\n]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers"
]
},
"description": "Create one or more sub rivers for a specific river_id. The river_id must use a source in question that supports sub rivers."
},
"response": []
},
{
"name": "Get data from specific sub river id",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers/{{subRiverId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers",
"{{subRiverId}}"
]
},
"description": "Retrieve information on a specific sub river that exist for a specific river_id."
},
"response": []
},
{
"name": "Update specific sub river by sub river id and river id",
"request": {
"method": "PATCH",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n\"sub_rivers\": [\n{\n\"name\": \"My Subriver\",\n\"description\": \"My Facebook clients sub river\",\n\"source\": {\n\"date_range\": {},\n\"report\": \"campaigns\",\n\"connection_id\": \"5fa7c995f5as82c6crfb9dd565\"\n},\n\"target\": {\n\"table_name\": \"ods_klaviyo_campaigns\",\n\"schema_name\": \"public\"\n},\n\"is_scheduled\": true,\n\"schedule\": {\n\"cron\": \"* 15 1/2 * * *\"\n},\n\"inherit_schedule\": true,\n\"is_enabled\": false\n}\n]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers/{{subRiverId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers",
"{{subRiverId}}"
]
},
"description": "Update a specific sub river specified by subriver_id and river_id."
},
"response": []
},
{
"name": "Delete sub river by id",
"request": {
"method": "DELETE",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/rivers/{{riverId}}/sub_rivers/{{subRiverId}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"rivers",
"{{riverId}}",
"sub_rivers",
"{{subRiverId}}"
]
},
"description": "Delete a sub river specified by subriver_id and river_id."
},
"response": []
}
],
"description": "Sub Rivers Management. Create / Read / Update / Delete Sub-Rivers values. Each value is validated and checked by the correlated key name of the column. Invalid key names will throw an error."
}
]
},
{
"name": "Run Rivers",
"item": [
{
"name": "Execute an existing river or sub river",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n\"river_id\": \"5e5fbbc2567409482d8511cd\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://console.rivery.io/api/run",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"run"
]
},
"description": "Use the river_id to execute an existing river or a sub river cross_id.\n\nYou can find the river id in the url of the river in the console e.g.\n\nhttps://console.rivery.io/#/river/{}/{}/river/{river_id}.\n\nThe sub river's cross_id can be found by using the GET sub rivers call, or by the id of every sub river in the console."
},
"response": []
},
{
"name": "Check the execution status of a river",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/check_run",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"check_run"
]
},
"description": "Use the run_id returned for the run endpoint to check the status of a river execution. \\n There are 4 available statuses for a river: \\n\n\nW = Waiting\nR = Running\nE = Error (failed), includes also the error message under error_description key.\nD - Done Successfully.\nOnce the river_run_status key is set to 'D' the river has finished successfully"
},
"response": []
}
],
"description": "Run rivers, check the run status and get run messages from the platform."
},
{
"name": "Activities",
"item": [
{
"name": "Download an existing run's logs of a River",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/activities/runs/logs?run_id",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"activities",
"runs",
"logs"
],
"query": [
{
"key": "query_id",
"value": null,
"disabled": true
},
{
"key": "run_id",
"value": null
}
]
},
"description": "Use run's id to fetch the logs of this specific run.\n\nYou can find the run id in the console, under the Activites tab\n\nPlease note that this call is an async call and will return a queryid param in the response To fetch the logs, please send the same request again with the provided queryid parameter"
},
"response": []
}
],
"description": "Activities. Monitor the river's current and previous runs. Logs are also available to download for some of the river types."
},
{
"name": "Data Connectors",
"item": [
{
"name": "Datasource Types",
"item": [
{
"name": "Get Datasource List",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/datasource_types",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"datasource_types"
]
},
"description": "Get a list of all datasources and targets configured in the Rivery account."
},
"response": []
},
{
"name": "Get Datasource List by Segment",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://console.rivery.io/api/datasource_types/{{segment}}",
"protocol": "https",
"host": [
"console",
"rivery",
"io"
],
"path": [
"api",
"datasource_types",
"{{segment}}"
]
},
"description": "Get a list of all data soures/targets in the Rivery account filtered by segment. Valid segment options are \"source\", \"target\", or \"connection\" (general)."
},
"response": []
}
]
}
]
}
],
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "",
"type": "string"
}
]
},
"event": [
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
}
],
"variable": [
{
"key": "access_token",
"value": ""
}
]
}