Boomi Data Integration API Reference (1.0.0) - MCP

Toggle Pane

• MCP
  • getGet Operation Status
  • getGet Data Flow Activities Runs
  • getGet Data Flow Activities Run
  • getGet Run Logs
  • postAdd Data Flow
  • getList Data Flows
  • putEdit Data Flow
  • delDelete Data Flow
  • getGet Data Flow
  • postActivate Data Flow
  • postDisable Data Flow
  • postRun Data Flow
  • getList Environments
  • getGet Connections
  • postAdd Connection
  • putUpdate Connection
  • delDelete Connection
  • getList Variables
  • putAdd Or Update Variables
• Operations
  • getGet Operation Status
• Activities
  • getGet Data Flow Activities Runs
  • getGet Data Flow Activities Run
  • getGet Run Logs
• Data Flows
  • postAdd Data Flow
  • getList Data Flows
  • putEdit Data Flow
  • delDelete Data Flow
  • getGet Data Flow
  • postActivate Data Flow
  • postDisable Data Flow
  • postRun Data Flow
• Environments
  • getList Environments
• Connections
  • getGet Connections
  • postAdd Connection
  • putUpdate Connection
  • delDelete Connection
• Variables
  • getList Variables
  • putAdd Or Update Variables

API docs by Redocly

Download OpenAPI Specification: Download

For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.

Find out more about Data Integration

MCP

Endpoints exposed by the Boomi Data Integration MCP server. Each carries the tool's usage instructions (parameters, prerequisites, gotchas).

Get Operation Status

Authorization scope: operations:list

For a given asynchronous operation ID, the endpoint returns its status.

---

📖 Instructions for usage

activate_data_flow, get_operation

activate_data_flow

Activate (schedule) a data flow so it runs on its configured schedule.

Set wait=True to block until activation completes or fails — eliminates
the need to manually call get_operation in a loop.
Returns the final operation status when wait=True.

get_operation

Get an activation/validation operation by its operation_id (24-char hex).

This is for activate_river / validate operations only.
For data run status, use get_run instead.

Authorizations:

HTTPBearer

path Parameters

operation_id required	string (Operation Id)
account_id required	string (Account Id)
environment_id required	string (Environment Id)

Responses

Response Schema: application/json

operation_id required	string (Operation Id) The ID of the operation
operation_type required	string (Operation Type) The type of the operation
run_id required	string (Run Id) The run id of the operation
last_update_date required	string <date-time> (Last Update Date) The date time in UTC timezone of the last update
status required	string (PullRequestStatus) Enum: "W" "E" "R" "D" The current status of the operation id
	Result (any) or Result (null) (Result) The result of the operation
	Error Message (string) or Error Message (null) (Error Message) The error message of the operation

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/operations/{operation_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/operations/{operation_id}

Response samples

• 200
• 422

Content type

application/json

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Get Data Flow Activities Runs

Authorization scope: activity:list

Get list of runs for a specific data flow in a specific time frame.

---

This endpoint return information about the runs.

---

📖 Instructions for usage

list_runs

List data runs for a data flow within a time range.

start_time and end_time must be ISO 8601 format, e.g. "2026-05-25T00:00:00".
Each item includes run_id, status, start_date_utc, end_date_utc, error_description.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

query Parameters

start_time required	string <date-time> (Start Time) Examples: start_time=2020-01-01T12:00:00 The start UTC date time. Time format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DDTHH:MM:SS.mmmmmm
end_time required	string <date-time> (End Time) Examples: end_time=2020-01-01T12:00:00 The end UTC date time. Time format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DDTHH:MM:SS.mmmmmm
	Target Name (string) or Target Name (null) (Target Name) Filter by the target table name
	Run Group Id (string) or Run Group Id (null) (Run Group Id) Filter by the run group ID
	Sub River Id (string) or Sub River Id (null) (Sub River Id) Filter by the sub river ID
page	integer (Page) >= 1 Default: 1
items_per_page	integer (Items Per Page) [ 1 .. 200 ] Default: 20
sort_by	string (Sort By) Default: "start_time" Enum: "units" "start_time" "table_name" Indicates by which parameter to sort the runs
sort_order	string (Sort Order) Default: "desc" Enum: "desc" "asc" Sorting can be either asc or desc, used in the api-service
cache_context_id	string (Cache Context Id) Cache context id is an internal query parameter for cache purposes

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
river_cross_id required	string (River Cross Id)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "run_id": "5658a1c9ea724ee59f048cbb5a6f734a",
    • "river_cross_id": "507f191e810c19729de860ea",
    • "datasource_id": "mysql",
    • "error_description": "error",
    • "units": 2.1,
    • "rpu": 2.1,
    • "run_group_id": "201dcf8182ad4a59868cb41b957fdc8d",
    • "status": "pending",
    • "source_name": "mysql",
    • "target_name": "table",
    • "start_date_utc": "2022-07-25T18:38:55.640Z",
    • "start_date_in_milliseconds": 1658774335000,
    • "end_date_utc": "2022-07-25T18:38:55.640Z",
    • "end_date_in_milliseconds": 1658774335000,
    • "sub_river_id": "507f191e810c19729de860ea",
    • "is_sub_river_run": false,
    • "is_high_frequency": false,
    • "pricing_category": "string"

    }

  ],
• "river_cross_id": "string"

}

Get Data Flow Activities Run

Authorization scope: activity:list

Get a specific run details.

---

📖 Instructions for usage

run_data_flow, get_run

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

get_run

Get the status and result of a data flow run by its run_id.

Use the run_group_id returned by run_data_flow as the run_id here.
Status is returned as a plain string: pending, running, success, failed.
Check error_description for failure details.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)
run_id required	string (Run Id)

Responses

Response Schema: application/json

run_id required	string (Run Id) The run ID
river_cross_id required	string (River Cross Id) The river cross ID
datasource_id required	string (Datasource Id) The datasource ID
required	Error Description (string) or Error Description (null) (Error Description) The error description if any
units required	number (Units) Total RPU (units)
rpu required	number (Rpu) Total RPU
run_group_id required	string (Run Group Id) The run group id
status required	string (ActivityStatusEnum) Enum: "pending" "canceled" "succeeded" "failed" "running" "skipped" The external status of a run (being used in the api)
source_name required	string (Source Name) The name of the source
start_date_utc required	string <date-time> (Start Date Utc) The start date time in UTC timezone.Time format YYYY-MM-DDThh:mm:ss.ms
start_date_in_milliseconds required	integer (Start Date In Milliseconds) The start epoch in milliseconds.
required	End Date Utc (string) or End Date Utc (null) (End Date Utc) The end date time in UTC timezone.Time format YYYY-MM-DDThh:mm:ss.ms
required	End Date In Milliseconds (integer) or End Date In Milliseconds (null) (End Date In Milliseconds) The end epoch in milliseconds.
is_sub_river_run required	boolean (Is Sub River Run) A flag that indicates whether this run is of a sub river or not
	Target Name (string) or Target Name (null) (Target Name) The target table name
	Sub River Id (string) or Sub River Id (null) (Sub River Id) The sub river id
	Is High Frequency (boolean) or Is High Frequency (null) (Is High Frequency) Default: false A flag that indicates whether this run is high frequency or not
	Pricing Category (string) or Pricing Category (null) (Pricing Category) The RPU policy rule object for calculating an RPU

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}

Response samples

• 200
• 422

Content type

application/json

{

• "run_id": "5658a1c9ea724ee59f048cbb5a6f734a",
• "river_cross_id": "507f191e810c19729de860ea",
• "datasource_id": "mysql",
• "error_description": "error",
• "units": 2.1,
• "rpu": 2.1,
• "run_group_id": "201dcf8182ad4a59868cb41b957fdc8d",
• "status": "pending",
• "source_name": "mysql",
• "target_name": "table",
• "start_date_utc": "2022-07-25T18:38:55.640Z",
• "start_date_in_milliseconds": 1658774335000,
• "end_date_utc": "2022-07-25T18:38:55.640Z",
• "end_date_in_milliseconds": 1658774335000,
• "sub_river_id": "507f191e810c19729de860ea",
• "is_sub_river_run": false,
• "is_high_frequency": false,
• "pricing_category": "string"

}

Get Run Logs

Authorization scope: activity:list

This method fetches the logs for a given run id of a data flow.

---

📖 Instructions for usage

get_run_logs

Download the logs for a specific data flow run as CSV text.

Returns raw CSV content with all log lines for the run.
Logs are only available for runs within the last 2 weeks.
If the response is empty, the data source may not support logs.

Use get_run first to confirm the run exists, then call this to fetch its logs.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)
run_id required	string (Run Id)

query Parameters

Array of Additional Services (strings) or Additional Services (null) (Additional Services) Additional services to query

Responses

Response Schema: text/html

string

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}/logs

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}/logs

Response samples

• 422

Content type

application/json

{

• "detail": [

  • {

    • "loc": [

      • "string"

      ],
    • "msg": "string",
    • "type": "string"

    }

  ]

}

Add Data Flow

Authorization scope: data flow:write

This endpoint creates a data flow.

---

📖 Instructions for usage

create_data_flow

Create a new source-to-target data flow.

Parameters
----------
name : Display name for the data flow.
source_name : Connector type for the source, as shown by list_connections —
    e.g. mysql, postgresql, snowflake, salesforce, hubspot, facebook ads, tiktok.
    Not an exhaustive list: new connectors are added regularly, so pass the type
    of your connection even if it is not listed here. (blueprint / blueprint_custom
    flows are created in the console, not here.)
source_connection_id : cross_id of the source connection (from list_connections).
target_name : Connector type for the target (same convention as source_name).
target_connection_id : cross_id of the target connection.
loading_method : How data is loaded into the target. Common values:
    append, merge, replace. Defaults to "append".
target_settings : Optional dict with target-specific fields, e.g.:
    {"database_name": "MY_DB", "schema_name": "PUBLIC", "table_name": "my_table"}
    Required fields vary by target connector type.

Note: blueprint / blueprint_custom (recipe) sources are NOT supported here — create
those flows in the Boomi Data Integration console.

To see a real example of this object, list your data flows and GET a similar one — use its definition as a reference.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

River Cross Id (string) or River Cross Id (null) (River Cross Id)

Request Body schema: application/json

required

name required	string (Name) The name of the river.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of river.
required	object (RiverMetadata) An object containing river metadata.
required	object (RiverSettings) An object containing river settings.
required	any (Properties) The properties of a river.
	RiverKindEnum (string) or null Default: "main_river" The kind of the river.
	Group Id (string) or Group Id (null) (Group Id) The id of the group the river belongs to.
	Group Name (string) or Group Name (null) (Group Name) The name of the group the river belongs to.
	Array of objects (Schedulers) [ 0 .. 1 ] items Default: [] An object containing the schedule settings. Currently support only one scheduler
	Cross Id (string) or Cross Id (null) (Cross Id) The cross_id of the river to be deployed.
	Deployment Definition (object) or Deployment Definition (null) (Deployment Definition) The deployment definition of the river to be deployed.
	Account Id (string) or Account Id (null) (Account Id) The account id.
	Environment Id (string) or Environment Id (null) (Environment Id) The environment id.
	Environment Name (string) or Environment Name (null) (Environment Name) The name of the environment.

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

Request samples

• Payload

Content type

application/json

{

• "name": "river_name",
• "kind": "main_river",
• "type": "source_to_target",
• "group_id": "55fr7d4270fdca16cac18261",
• "group_name": "river_group_1",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active"

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "schedulers": [ ],
• "cross_id": "string",
• "deployment_definition": { },
• "account_id": "62e7f4352c13160013dc39be",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment"

}

Response samples

• 201
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

List Data Flows

Authorization scope: data flow:list

This endpoint gets a summary of all the data flows in an environment

---

📖 Instructions for usage

list_data_flows

List data flows by name or status. Do NOT call this speculatively.

Before calling, ask the user what they want to do. You can:
- Run a data flow → ask for the name, then call list_data_flows(name=<name>)
- Check run status → ask which flow and use get_run / list_runs
- Create a new flow → use create_data_flow
- Update a flow → ask for the name, then get it and patch it

Always filter by name when the user mentions a specific flow.
Only list without a filter if the user explicitly asks to see all flows.
Returns items plus pagination metadata (total_items, page, has_next).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.
items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
	Group Name (string) or Group Name (null) (Group Name) The river group name
	Array of Group Id (strings) or Group Id (null) (Group Id) Examples: group_id=5f5b17b0a10e07a4ff4c33 The river group id
	Name (string) or Name (null) (Name) The river name
	RiverScheduleStatusEnum (string) or Schedule (null) (Schedule) The river schedule status
river_status	Array of strings (River Status) Default: "" Items Enum: "active" "disabled" Examples: river_status=active The river status
	RiverInterfaceEnum (string) or Interface Type (null) (Interface Type) The rivers interface type
include_deleted	boolean (Include Deleted) Default: false
sort_by	string (Sort By) Default: "last_updated_at" Enum: "last_updated_at" "source_name" "river_name" "group_name" "group_id" The river sort by filter
sort_order	string (Sort Order) Default: "desc" Enum: "desc" "asc" The river sort order filter
	(Array of River Type (RiverTypeInternalEnum (string) or RiverTypeEnum (string))) or River Type (null) (River Type) The river type

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "name": "river_name",
    • "river_status": "active",
    • "group_name": "river_group_1",
    • "group_id": "62e7f4352c13160013dc39be",
    • "river_schedulers": [

      • "0 * * * *",
      • "0 0 1 * *"

      ],
    • "datasource_id": "5f7d4270fdca16cac18261",
    • "last_user_name_modified": "user_name",
    • "river_cross_id": "5f7d4270fdca16cac18261",
    • "last_updated_at": "2021-01-01T00:00:00.000Z",
    • "description": "river_description",
    • "is_api_v2": true,
    • "river_type": "source_to_target",
    • "created_at": "2021-01-01T00:00:00.000Z"

    }

  ]

}

Edit Data Flow

Authorization scope: data flow:write

This endpoint updates a data flow.

---

📖 Instructions for usage

update_data_flow, set_data_flow_source_tables, patch_data_flow

update_data_flow

Update an existing data flow. body must match the UpdateRiver API schema.

To add source tables, use set_data_flow_source_tables instead — it handles
the correct schema grouping automatically.

set_data_flow_source_tables

Set the source tables on a data flow by name.

Looks up the correct schema grouping from the connection and builds the
data flow schemas structure automatically. Use this instead of update_data_flow
when you want to select which tables to sync.

Note: this performs a GET-then-PUT with no locking. Concurrent calls on
the same data_flow_id will overwrite each other (last write wins).
Avoid calling this on the same data flow from multiple agents simultaneously.

Parameters
----------
data_flow_id : The data flow to update.
source_connection_id : The source connection cross_id (from list_connections).
table_names : ALL table/object names to sync on this data flow, e.g. ["Account", "Contact"].
              Pass every table you want in one call — this replaces the entire table
              selection. One data flow handles multiple tables; do not create a separate
              data flow per table.
              Names are matched case-insensitively against the connection's table list.

patch_data_flow

Partially update a data flow — only supply the fields you want to change.

Fetches the current data flow, deep-merges patch into it, then PUTs it back.
Much simpler than update_data_flow when you only want to change one or two fields.

IMPORTANT — lists are REPLACED, not merged. Do NOT use this to add or change
source tables (properties.schemas). Use set_data_flow_source_tables instead, which
handles table selection correctly and keeps all tables in one data flow.

Examples
--------
Change target schema only:
    patch={"properties": {"target": {"schema_name": "PUBLIC"}}}

Rename the data flow:
    patch={"name": "New Name"}

Note: GET-then-PUT with no locking — concurrent calls on the same data flow
will overwrite each other (last write wins).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Request Body schema: application/json

required

name required	string (Name) The name of the river.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of river.
required	object (RiverMetadata) An object containing river metadata.
required	object (RiverSettings) An object containing river settings.
required	any (Properties) The properties of a river.
	RiverKindEnum (string) or null Default: "main_river" The kind of the river.
	Group Id (string) or Group Id (null) (Group Id) The id of the group the river belongs to.
	Group Name (string) or Group Name (null) (Group Name) The name of the group the river belongs to.
	Array of objects (Schedulers) [ 0 .. 1 ] items Default: [] An object containing the schedule settings. Currently support only one scheduler
	Cross Id (string) or Cross Id (null) (Cross Id) The cross_id of the river to be deployed.
	Deployment Definition (object) or Deployment Definition (null) (Deployment Definition) The deployment definition of the river to be deployed.
	Account Id (string) or Account Id (null) (Account Id) The account id.
	Environment Id (string) or Environment Id (null) (Environment Id) The environment id.
	Environment Name (string) or Environment Name (null) (Environment Name) The name of the environment.

Responses

Response Schema: application/json

cross_id required	string (Cross Id) The river cross id.
account_id required	string (Account Id) The account id.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of the river.
name required	string (Name) The name of the river.
environment_id required	string (Environment Id) The environment cross id.
environment_name required	string (Environment Name) The environment name.
group_id required	string (Group Id) The group id.
group_name required	string (Group Name) The group name.
required	object (RiverMetadataExtended) The river metadata.
required	any (Properties) The river properties, will change according to the river type.
kind	string (RiverKindEnum) Default: "main_river" Enum: "sub_river" "main_river" The kind of the river.
	RiverSettings (object) or null River settings.
	Array of Schedulers (objects) or Schedulers (null) (Schedulers) Default: [] River schedulers.

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Request samples

• Payload

Content type

application/json

{

• "name": "river_name",
• "kind": "main_river",
• "type": "source_to_target",
• "group_id": "55fr7d4270fdca16cac18261",
• "group_name": "river_group_1",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active"

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "schedulers": [ ],
• "cross_id": "string",
• "deployment_definition": { },
• "account_id": "62e7f4352c13160013dc39be",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment"

}

Response samples

• 200
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

Delete Data Flow

Authorization scope: data flow:write

This endpoint deletes a data flow

---

📖 Instructions for usage

delete_data_flow

Delete a data flow.

The upstream DELETE returns an empty body on success; this returns
{"deleted": true, "data_flow_id": ...}. Deleting an ACTIVE flow returns a 400
(surfaced verbatim) — call disable_data_flow first, then delete. This never
force-deletes.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

Response Schema: application/json

any

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Response samples

• 200
• 422

Content type

application/json

null

Get Data Flow

Authorization scope: data flow:list

This endpoint gets a data flow.

---

📖 Instructions for usage

get_data_flow, set_data_flow_source_tables, run_data_flow, patch_data_flow

get_data_flow

Get full details of a data flow by its ID.

Note: only works for data flows created via the API (is_api_v2=true).
Data flows created in the Boomi Data Integration UI will return a 400 error.
Use list_data_flows to find data_flow_id values.

set_data_flow_source_tables

Set the source tables on a data flow by name.

Looks up the correct schema grouping from the connection and builds the
data flow schemas structure automatically. Use this instead of update_data_flow
when you want to select which tables to sync.

Note: this performs a GET-then-PUT with no locking. Concurrent calls on
the same data_flow_id will overwrite each other (last write wins).
Avoid calling this on the same data flow from multiple agents simultaneously.

Parameters
----------
data_flow_id : The data flow to update.
source_connection_id : The source connection cross_id (from list_connections).
table_names : ALL table/object names to sync on this data flow, e.g. ["Account", "Contact"].
              Pass every table you want in one call — this replaces the entire table
              selection. One data flow handles multiple tables; do not create a separate
              data flow per table.
              Names are matched case-insensitively against the connection's table list.

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

patch_data_flow

Partially update a data flow — only supply the fields you want to change.

Fetches the current data flow, deep-merges patch into it, then PUTs it back.
Much simpler than update_data_flow when you only want to change one or two fields.

IMPORTANT — lists are REPLACED, not merged. Do NOT use this to add or change
source tables (properties.schemas). Use set_data_flow_source_tables instead, which
handles table selection correctly and keeps all tables in one data flow.

Examples
--------
Change target schema only:
    patch={"properties": {"target": {"schema_name": "PUBLIC"}}}

Rename the data flow:
    patch={"name": "New Name"}

Note: GET-then-PUT with no locking — concurrent calls on the same data flow
will overwrite each other (last write wins).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

Response Schema: application/json

cross_id required	string (Cross Id) The river cross id.
account_id required	string (Account Id) The account id.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of the river.
name required	string (Name) The name of the river.
environment_id required	string (Environment Id) The environment cross id.
environment_name required	string (Environment Name) The environment name.
group_id required	string (Group Id) The group id.
group_name required	string (Group Name) The group name.
required	object (RiverMetadataExtended) The river metadata.
required	any (Properties) The river properties, will change according to the river type.
kind	string (RiverKindEnum) Default: "main_river" Enum: "sub_river" "main_river" The kind of the river.
	RiverSettings (object) or null River settings.
	Array of Schedulers (objects) or Schedulers (null) (Schedulers) Default: [] River schedulers.

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Response samples

• 200
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

Activate Data Flow

Authorization scope: data flow:write

This endpoint activates a data flow for allowing it to run.

---

📖 Instructions for usage

activate_data_flow

Activate (schedule) a data flow so it runs on its configured schedule.

Set wait=True to block until activation completes or fails — eliminates
the need to manually call get_operation in a loop.
Returns the final operation status when wait=True.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/activate_river

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/activate_river

Response samples

• 202
• 422

Content type

application/json

Example

OperationResponseResponse Activate RiverOperationResponse

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Disable Data Flow

Authorization scope: data flow:write

This endpoint disables a data flow to forbid it from running.

---

📖 Instructions for usage

disable_data_flow

Disable (pause) a data flow's schedule without deleting it.

Returns {"disabled": true, "data_flow_id": ...} (the upstream may return an empty body).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/disable_river

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/disable_river

Response samples

• 202
• 422

Content type

application/json

Example

OperationResponseResponse Disable RiverOperationResponse

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Run Data Flow

Authorization scope: data flow:execute

This endpoint runs a data flow.

---

Throttling rules: *** Data Flow can be executed up to 2 times per minute** *** Each user can execute a data flow up to 15 times per minute**

---

📖 Instructions for usage

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

query Parameters

run_sub_rivers

boolean (Run Sub Rivers) Default: false A flag that indicates whether to run all active sub rivers of the master river

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/run

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/run

Response samples

• 202
• 422

Content type

application/json

{

• "runs": [

  • {

    • "sub_river_id": "62e7f4352c13160013dc39be",
    • "run_id": "1f1468d097754cd8892468c2763ebfe8",
    • "status": "pending",
    • "message": "The river is already in progress."

    }

  ],
• "river_cross_id": "string",
• "run_group_id": "string"

}

List Environments

Authorization scope: environment:list

Get list of environments entities for an account

---

📖 Instructions for usage

list_environments

List all environments for an account.

Authorizations:

HTTPBearer

path Parameters

account_id required

string (Account Id)

query Parameters

include_deleted	boolean (Include Deleted) Default: false
is_deployable_environments	boolean (Is Deployable Environments) Default: false
items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "items": [

  • {

    • "_id": "633ede20f1fc5500111fd7b3",
    • "account": "62e7f4352c13160013dc39be",
    • "user_created": "62e7f4352c13160013dc39be",
    • "created_at": "2022-07-25T18:38:55.640Z",
    • "cross_id": "62e7f4352c13160013dc39be",
    • "updated_at": "2022-08-02T13:38:44.054000",
    • "environment_name": "Dev Environment",
    • "color": "Gray",
    • "description": "Development environment for new rivers",
    • "variables": {

      • "aws_file_zone": "Rivery-rivery",
      • "azure_file_zone": "Rivery-rivery",
      • "days_ago": "0",
      • "gcs_file_zone": "Rivery-rivery",
      • "hours_offset": "0"

      },
    • "is_deleted": false,
    • "deleted_by": "62e7f4352c13160013dc39be",
    • "deleted_at": "2022-07-25T18:38:55.640Z",
    • "is_default": true,
    • "updated_by": "62e7f4352c13160013dc39be",
    • "is_delete_lock": true

    }

  ]

}

Get Connections

Authorization scope: connection:list

Get all connection entities as a paginated list

---

📖 Instructions for usage

list_connections

List all connections in an environment (sweeps every page in one call).

Returns {items, total_items, page, has_next}. Each item includes connection_name,
connection_type, connection_type_id, and cross_id; use cross_id as connection_id
when creating data flows. If the upstream 500s on a specific page, that page is
skipped and its number is reported under "incomplete_pages" rather than failing
the whole listing.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "account_id": "string",
    • "environment_id": "string",
    • "cross_id": "5f887c764c40e5598f717676",
    • "_id": "5f887c764c40e5598f717676",
    • "connection_name": "test connection",
    • "connection_type": "Oracle",
    • "connection_type_id": "oracle",
    • "is_test_connection": false,
    • "connection_update_by": "5f887c764c40e5598f717676",
    • "connection_update_time": "2019-08-24T14:15:22Z"

    }

  ]

}

Add Connection

Authorization scope: connection:edit

Creates a new connection entity.

---

📖 Instructions for usage

create_connection

Create a new connection. body must match the CreateConnection API schema.

NOT ALL CONNECTION TYPES CAN BE CREATED HERE. Connections that authenticate
via OAuth (e.g. Google services, Salesforce, HubSpot, Facebook/Meta, LinkedIn,
and similar — anything that needs a browser sign-in / "Connect with..." flow)
CANNOT be created through this tool, because OAuth requires an interactive
browser consent step. For those, tell the user:
"This connection uses OAuth — please create it in the Boomi Data Integration
console, then I can use it here."

This tool works for connections that authenticate with credentials you can
supply directly (host/port/user/password/keys), e.g. databases like mysql,
postgresql, mssql, snowflake, bigquery, redshift, mongodb.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Request Body schema: application/json

required

object (Connection To Create)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 201
• 422

Content type

application/json

{ }

Update Connection

Authorization scope: connection:edit

This endpoint updates a connection

---

📖 Instructions for usage

update_connection

Update an existing connection.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
cross_id required	string (Cross Id)

Request Body schema: application/json

required

object (Connection To Update)

Responses

Response Schema: application/json

object (Response Update Connection)

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{cross_id}

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 422

Content type

application/json

{ }

Delete Connection

Authorization scope: connection:delete

This endpoint deletes a connection

---

📖 Instructions for usage

delete_connection

Delete a connection.

The upstream DELETE returns an empty body on success; this returns
{"deleted": true, "connection_id": ...}.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
connection_cross_id required	string (Connection Cross Id)

Responses

Response Schema: application/json

any

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{connection_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{connection_cross_id}

Response samples

• 200
• 422

Content type

application/json

null

List Variables

Authorization scope: variables:list

List variables

---

📖 Instructions for usage

list_variables

List all variables in an environment.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Responses

Response Schema: application/json

variables required

object (Variables)

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

Response samples

• 200
• 422

Content type

application/json

{

• "variables": { }

}

Add Or Update Variables

Authorization scope: variables:edit

Add new variable or update existing one for environment

---

📖 Instructions for usage

upsert_variables

Create or update variables in an environment.

Each item in variables should be: {"name": "VAR_NAME", "value": "some_value"}.

Returns {"updated": true, "count": N} (the upstream may return an empty body).

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Request Body schema: application/json

required

variables required

object (Variables)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

Request samples

• Payload

Content type

application/json

{

• "variables": { }

}

Response samples

• 201
• 422

Content type

application/json

{

• "variables": { }

}

Operations

Get Operation Status

Authorization scope: operations:list

For a given asynchronous operation ID, the endpoint returns its status.

---

📖 Instructions for usage

activate_data_flow, get_operation

activate_data_flow

Activate (schedule) a data flow so it runs on its configured schedule.

Set wait=True to block until activation completes or fails — eliminates
the need to manually call get_operation in a loop.
Returns the final operation status when wait=True.

get_operation

Get an activation/validation operation by its operation_id (24-char hex).

This is for activate_river / validate operations only.
For data run status, use get_run instead.

Authorizations:

HTTPBearer

path Parameters

operation_id required	string (Operation Id)
account_id required	string (Account Id)
environment_id required	string (Environment Id)

Responses

Response Schema: application/json

operation_id required	string (Operation Id) The ID of the operation
operation_type required	string (Operation Type) The type of the operation
run_id required	string (Run Id) The run id of the operation
last_update_date required	string <date-time> (Last Update Date) The date time in UTC timezone of the last update
status required	string (PullRequestStatus) Enum: "W" "E" "R" "D" The current status of the operation id
	Result (any) or Result (null) (Result) The result of the operation
	Error Message (string) or Error Message (null) (Error Message) The error message of the operation

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/operations/{operation_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/operations/{operation_id}

Response samples

• 200
• 422

Content type

application/json

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Activities

Get Data Flow Activities Runs

Authorization scope: activity:list

Get list of runs for a specific data flow in a specific time frame.

---

This endpoint return information about the runs.

---

📖 Instructions for usage

list_runs

List data runs for a data flow within a time range.

start_time and end_time must be ISO 8601 format, e.g. "2026-05-25T00:00:00".
Each item includes run_id, status, start_date_utc, end_date_utc, error_description.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

query Parameters

start_time required	string <date-time> (Start Time) Examples: start_time=2020-01-01T12:00:00 The start UTC date time. Time format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DDTHH:MM:SS.mmmmmm
end_time required	string <date-time> (End Time) Examples: end_time=2020-01-01T12:00:00 The end UTC date time. Time format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DDTHH:MM:SS.mmmmmm
	Target Name (string) or Target Name (null) (Target Name) Filter by the target table name
	Run Group Id (string) or Run Group Id (null) (Run Group Id) Filter by the run group ID
	Sub River Id (string) or Sub River Id (null) (Sub River Id) Filter by the sub river ID
page	integer (Page) >= 1 Default: 1
items_per_page	integer (Items Per Page) [ 1 .. 200 ] Default: 20
sort_by	string (Sort By) Default: "start_time" Enum: "units" "start_time" "table_name" Indicates by which parameter to sort the runs
sort_order	string (Sort Order) Default: "desc" Enum: "desc" "asc" Sorting can be either asc or desc, used in the api-service
cache_context_id	string (Cache Context Id) Cache context id is an internal query parameter for cache purposes

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
river_cross_id required	string (River Cross Id)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "run_id": "5658a1c9ea724ee59f048cbb5a6f734a",
    • "river_cross_id": "507f191e810c19729de860ea",
    • "datasource_id": "mysql",
    • "error_description": "error",
    • "units": 2.1,
    • "rpu": 2.1,
    • "run_group_id": "201dcf8182ad4a59868cb41b957fdc8d",
    • "status": "pending",
    • "source_name": "mysql",
    • "target_name": "table",
    • "start_date_utc": "2022-07-25T18:38:55.640Z",
    • "start_date_in_milliseconds": 1658774335000,
    • "end_date_utc": "2022-07-25T18:38:55.640Z",
    • "end_date_in_milliseconds": 1658774335000,
    • "sub_river_id": "507f191e810c19729de860ea",
    • "is_sub_river_run": false,
    • "is_high_frequency": false,
    • "pricing_category": "string"

    }

  ],
• "river_cross_id": "string"

}

Get Data Flow Activities Run

Authorization scope: activity:list

Get a specific run details.

---

📖 Instructions for usage

run_data_flow, get_run

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

get_run

Get the status and result of a data flow run by its run_id.

Use the run_group_id returned by run_data_flow as the run_id here.
Status is returned as a plain string: pending, running, success, failed.
Check error_description for failure details.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)
run_id required	string (Run Id)

Responses

Response Schema: application/json

run_id required	string (Run Id) The run ID
river_cross_id required	string (River Cross Id) The river cross ID
datasource_id required	string (Datasource Id) The datasource ID
required	Error Description (string) or Error Description (null) (Error Description) The error description if any
units required	number (Units) Total RPU (units)
rpu required	number (Rpu) Total RPU
run_group_id required	string (Run Group Id) The run group id
status required	string (ActivityStatusEnum) Enum: "pending" "canceled" "succeeded" "failed" "running" "skipped" The external status of a run (being used in the api)
source_name required	string (Source Name) The name of the source
start_date_utc required	string <date-time> (Start Date Utc) The start date time in UTC timezone.Time format YYYY-MM-DDThh:mm:ss.ms
start_date_in_milliseconds required	integer (Start Date In Milliseconds) The start epoch in milliseconds.
required	End Date Utc (string) or End Date Utc (null) (End Date Utc) The end date time in UTC timezone.Time format YYYY-MM-DDThh:mm:ss.ms
required	End Date In Milliseconds (integer) or End Date In Milliseconds (null) (End Date In Milliseconds) The end epoch in milliseconds.
is_sub_river_run required	boolean (Is Sub River Run) A flag that indicates whether this run is of a sub river or not
	Target Name (string) or Target Name (null) (Target Name) The target table name
	Sub River Id (string) or Sub River Id (null) (Sub River Id) The sub river id
	Is High Frequency (boolean) or Is High Frequency (null) (Is High Frequency) Default: false A flag that indicates whether this run is high frequency or not
	Pricing Category (string) or Pricing Category (null) (Pricing Category) The RPU policy rule object for calculating an RPU

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}

Response samples

• 200
• 422

Content type

application/json

{

• "run_id": "5658a1c9ea724ee59f048cbb5a6f734a",
• "river_cross_id": "507f191e810c19729de860ea",
• "datasource_id": "mysql",
• "error_description": "error",
• "units": 2.1,
• "rpu": 2.1,
• "run_group_id": "201dcf8182ad4a59868cb41b957fdc8d",
• "status": "pending",
• "source_name": "mysql",
• "target_name": "table",
• "start_date_utc": "2022-07-25T18:38:55.640Z",
• "start_date_in_milliseconds": 1658774335000,
• "end_date_utc": "2022-07-25T18:38:55.640Z",
• "end_date_in_milliseconds": 1658774335000,
• "sub_river_id": "507f191e810c19729de860ea",
• "is_sub_river_run": false,
• "is_high_frequency": false,
• "pricing_category": "string"

}

Get Run Logs

Authorization scope: activity:list

This method fetches the logs for a given run id of a data flow.

---

📖 Instructions for usage

get_run_logs

Download the logs for a specific data flow run as CSV text.

Returns raw CSV content with all log lines for the run.
Logs are only available for runs within the last 2 weeks.
If the response is empty, the data source may not support logs.

Use get_run first to confirm the run exists, then call this to fetch its logs.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)
run_id required	string (Run Id)

query Parameters

Array of Additional Services (strings) or Additional Services (null) (Additional Services) Additional services to query

Responses

Response Schema: text/html

string

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}/logs

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/runs/{run_id}/logs

Response samples

• 422

Content type

application/json

{

• "detail": [

  • {

    • "loc": [

      • "string"

      ],
    • "msg": "string",
    • "type": "string"

    }

  ]

}

Data Flows

Add Data Flow

Authorization scope: data flow:write

This endpoint creates a data flow.

---

📖 Instructions for usage

create_data_flow

Create a new source-to-target data flow.

Parameters
----------
name : Display name for the data flow.
source_name : Connector type for the source, as shown by list_connections —
    e.g. mysql, postgresql, snowflake, salesforce, hubspot, facebook ads, tiktok.
    Not an exhaustive list: new connectors are added regularly, so pass the type
    of your connection even if it is not listed here. (blueprint / blueprint_custom
    flows are created in the console, not here.)
source_connection_id : cross_id of the source connection (from list_connections).
target_name : Connector type for the target (same convention as source_name).
target_connection_id : cross_id of the target connection.
loading_method : How data is loaded into the target. Common values:
    append, merge, replace. Defaults to "append".
target_settings : Optional dict with target-specific fields, e.g.:
    {"database_name": "MY_DB", "schema_name": "PUBLIC", "table_name": "my_table"}
    Required fields vary by target connector type.

Note: blueprint / blueprint_custom (recipe) sources are NOT supported here — create
those flows in the Boomi Data Integration console.

To see a real example of this object, list your data flows and GET a similar one — use its definition as a reference.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

River Cross Id (string) or River Cross Id (null) (River Cross Id)

Request Body schema: application/json

required

name required	string (Name) The name of the river.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of river.
required	object (RiverMetadata) An object containing river metadata.
required	object (RiverSettings) An object containing river settings.
required	any (Properties) The properties of a river.
	RiverKindEnum (string) or null Default: "main_river" The kind of the river.
	Group Id (string) or Group Id (null) (Group Id) The id of the group the river belongs to.
	Group Name (string) or Group Name (null) (Group Name) The name of the group the river belongs to.
	Array of objects (Schedulers) [ 0 .. 1 ] items Default: [] An object containing the schedule settings. Currently support only one scheduler
	Cross Id (string) or Cross Id (null) (Cross Id) The cross_id of the river to be deployed.
	Deployment Definition (object) or Deployment Definition (null) (Deployment Definition) The deployment definition of the river to be deployed.
	Account Id (string) or Account Id (null) (Account Id) The account id.
	Environment Id (string) or Environment Id (null) (Environment Id) The environment id.
	Environment Name (string) or Environment Name (null) (Environment Name) The name of the environment.

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

Request samples

• Payload

Content type

application/json

{

• "name": "river_name",
• "kind": "main_river",
• "type": "source_to_target",
• "group_id": "55fr7d4270fdca16cac18261",
• "group_name": "river_group_1",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active"

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "schedulers": [ ],
• "cross_id": "string",
• "deployment_definition": { },
• "account_id": "62e7f4352c13160013dc39be",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment"

}

Response samples

• 201
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

List Data Flows

Authorization scope: data flow:list

This endpoint gets a summary of all the data flows in an environment

---

📖 Instructions for usage

list_data_flows

List data flows by name or status. Do NOT call this speculatively.

Before calling, ask the user what they want to do. You can:
- Run a data flow → ask for the name, then call list_data_flows(name=<name>)
- Check run status → ask which flow and use get_run / list_runs
- Create a new flow → use create_data_flow
- Update a flow → ask for the name, then get it and patch it

Always filter by name when the user mentions a specific flow.
Only list without a filter if the user explicitly asks to see all flows.
Returns items plus pagination metadata (total_items, page, has_next).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.
items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
	Group Name (string) or Group Name (null) (Group Name) The river group name
	Array of Group Id (strings) or Group Id (null) (Group Id) Examples: group_id=5f5b17b0a10e07a4ff4c33 The river group id
	Name (string) or Name (null) (Name) The river name
	RiverScheduleStatusEnum (string) or Schedule (null) (Schedule) The river schedule status
river_status	Array of strings (River Status) Default: "" Items Enum: "active" "disabled" Examples: river_status=active The river status
	RiverInterfaceEnum (string) or Interface Type (null) (Interface Type) The rivers interface type
include_deleted	boolean (Include Deleted) Default: false
sort_by	string (Sort By) Default: "last_updated_at" Enum: "last_updated_at" "source_name" "river_name" "group_name" "group_id" The river sort by filter
sort_order	string (Sort Order) Default: "desc" Enum: "desc" "asc" The river sort order filter
	(Array of River Type (RiverTypeInternalEnum (string) or RiverTypeEnum (string))) or River Type (null) (River Type) The river type

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "name": "river_name",
    • "river_status": "active",
    • "group_name": "river_group_1",
    • "group_id": "62e7f4352c13160013dc39be",
    • "river_schedulers": [

      • "0 * * * *",
      • "0 0 1 * *"

      ],
    • "datasource_id": "5f7d4270fdca16cac18261",
    • "last_user_name_modified": "user_name",
    • "river_cross_id": "5f7d4270fdca16cac18261",
    • "last_updated_at": "2021-01-01T00:00:00.000Z",
    • "description": "river_description",
    • "is_api_v2": true,
    • "river_type": "source_to_target",
    • "created_at": "2021-01-01T00:00:00.000Z"

    }

  ]

}

Edit Data Flow

Authorization scope: data flow:write

This endpoint updates a data flow.

---

📖 Instructions for usage

update_data_flow, set_data_flow_source_tables, patch_data_flow

update_data_flow

Update an existing data flow. body must match the UpdateRiver API schema.

To add source tables, use set_data_flow_source_tables instead — it handles
the correct schema grouping automatically.

set_data_flow_source_tables

Set the source tables on a data flow by name.

Looks up the correct schema grouping from the connection and builds the
data flow schemas structure automatically. Use this instead of update_data_flow
when you want to select which tables to sync.

Note: this performs a GET-then-PUT with no locking. Concurrent calls on
the same data_flow_id will overwrite each other (last write wins).
Avoid calling this on the same data flow from multiple agents simultaneously.

Parameters
----------
data_flow_id : The data flow to update.
source_connection_id : The source connection cross_id (from list_connections).
table_names : ALL table/object names to sync on this data flow, e.g. ["Account", "Contact"].
              Pass every table you want in one call — this replaces the entire table
              selection. One data flow handles multiple tables; do not create a separate
              data flow per table.
              Names are matched case-insensitively against the connection's table list.

patch_data_flow

Partially update a data flow — only supply the fields you want to change.

Fetches the current data flow, deep-merges patch into it, then PUTs it back.
Much simpler than update_data_flow when you only want to change one or two fields.

IMPORTANT — lists are REPLACED, not merged. Do NOT use this to add or change
source tables (properties.schemas). Use set_data_flow_source_tables instead, which
handles table selection correctly and keeps all tables in one data flow.

Examples
--------
Change target schema only:
    patch={"properties": {"target": {"schema_name": "PUBLIC"}}}

Rename the data flow:
    patch={"name": "New Name"}

Note: GET-then-PUT with no locking — concurrent calls on the same data flow
will overwrite each other (last write wins).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Request Body schema: application/json

required

name required	string (Name) The name of the river.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of river.
required	object (RiverMetadata) An object containing river metadata.
required	object (RiverSettings) An object containing river settings.
required	any (Properties) The properties of a river.
	RiverKindEnum (string) or null Default: "main_river" The kind of the river.
	Group Id (string) or Group Id (null) (Group Id) The id of the group the river belongs to.
	Group Name (string) or Group Name (null) (Group Name) The name of the group the river belongs to.
	Array of objects (Schedulers) [ 0 .. 1 ] items Default: [] An object containing the schedule settings. Currently support only one scheduler
	Cross Id (string) or Cross Id (null) (Cross Id) The cross_id of the river to be deployed.
	Deployment Definition (object) or Deployment Definition (null) (Deployment Definition) The deployment definition of the river to be deployed.
	Account Id (string) or Account Id (null) (Account Id) The account id.
	Environment Id (string) or Environment Id (null) (Environment Id) The environment id.
	Environment Name (string) or Environment Name (null) (Environment Name) The name of the environment.

Responses

Response Schema: application/json

cross_id required	string (Cross Id) The river cross id.
account_id required	string (Account Id) The account id.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of the river.
name required	string (Name) The name of the river.
environment_id required	string (Environment Id) The environment cross id.
environment_name required	string (Environment Name) The environment name.
group_id required	string (Group Id) The group id.
group_name required	string (Group Name) The group name.
required	object (RiverMetadataExtended) The river metadata.
required	any (Properties) The river properties, will change according to the river type.
kind	string (RiverKindEnum) Default: "main_river" Enum: "sub_river" "main_river" The kind of the river.
	RiverSettings (object) or null River settings.
	Array of Schedulers (objects) or Schedulers (null) (Schedulers) Default: [] River schedulers.

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Request samples

• Payload

Content type

application/json

{

• "name": "river_name",
• "kind": "main_river",
• "type": "source_to_target",
• "group_id": "55fr7d4270fdca16cac18261",
• "group_name": "river_group_1",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active"

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "schedulers": [ ],
• "cross_id": "string",
• "deployment_definition": { },
• "account_id": "62e7f4352c13160013dc39be",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment"

}

Response samples

• 200
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

Delete Data Flow

Authorization scope: data flow:write

This endpoint deletes a data flow

---

📖 Instructions for usage

delete_data_flow

Delete a data flow.

The upstream DELETE returns an empty body on success; this returns
{"deleted": true, "data_flow_id": ...}. Deleting an ACTIVE flow returns a 400
(surfaced verbatim) — call disable_data_flow first, then delete. This never
force-deletes.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

Response Schema: application/json

any

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Response samples

• 200
• 422

Content type

application/json

null

Get Data Flow

Authorization scope: data flow:list

This endpoint gets a data flow.

---

📖 Instructions for usage

get_data_flow, set_data_flow_source_tables, run_data_flow, patch_data_flow

get_data_flow

Get full details of a data flow by its ID.

Note: only works for data flows created via the API (is_api_v2=true).
Data flows created in the Boomi Data Integration UI will return a 400 error.
Use list_data_flows to find data_flow_id values.

set_data_flow_source_tables

Set the source tables on a data flow by name.

Looks up the correct schema grouping from the connection and builds the
data flow schemas structure automatically. Use this instead of update_data_flow
when you want to select which tables to sync.

Note: this performs a GET-then-PUT with no locking. Concurrent calls on
the same data_flow_id will overwrite each other (last write wins).
Avoid calling this on the same data flow from multiple agents simultaneously.

Parameters
----------
data_flow_id : The data flow to update.
source_connection_id : The source connection cross_id (from list_connections).
table_names : ALL table/object names to sync on this data flow, e.g. ["Account", "Contact"].
              Pass every table you want in one call — this replaces the entire table
              selection. One data flow handles multiple tables; do not create a separate
              data flow per table.
              Names are matched case-insensitively against the connection's table list.

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

patch_data_flow

Partially update a data flow — only supply the fields you want to change.

Fetches the current data flow, deep-merges patch into it, then PUTs it back.
Much simpler than update_data_flow when you only want to change one or two fields.

IMPORTANT — lists are REPLACED, not merged. Do NOT use this to add or change
source tables (properties.schemas). Use set_data_flow_source_tables instead, which
handles table selection correctly and keeps all tables in one data flow.

Examples
--------
Change target schema only:
    patch={"properties": {"target": {"schema_name": "PUBLIC"}}}

Rename the data flow:
    patch={"name": "New Name"}

Note: GET-then-PUT with no locking — concurrent calls on the same data flow
will overwrite each other (last write wins).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

Response Schema: application/json

cross_id required	string (Cross Id) The river cross id.
account_id required	string (Account Id) The account id.
type required	string (RiverTypeEnum) Enum: "source_to_target" "actions" "logic" "connector_executor" The type of the river.
name required	string (Name) The name of the river.
environment_id required	string (Environment Id) The environment cross id.
environment_name required	string (Environment Name) The environment name.
group_id required	string (Group Id) The group id.
group_name required	string (Group Name) The group name.
required	object (RiverMetadataExtended) The river metadata.
required	any (Properties) The river properties, will change according to the river type.
kind	string (RiverKindEnum) Default: "main_river" Enum: "sub_river" "main_river" The kind of the river.
	RiverSettings (object) or null River settings.
	Array of Schedulers (objects) or Schedulers (null) (Schedulers) Default: [] River schedulers.

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}

Response samples

• 200
• 422

Content type

application/json

{

• "cross_id": "62e7f4352c13160013dc39be",
• "account_id": "62e7f4352c13160013dc39be",
• "kind": "main_river",
• "type": "source_to_target",
• "name": "my_river",
• "environment_id": "62e7f4352c13160013dc39be",
• "environment_name": "my_environment",
• "group_id": "62e7f4352c13160013dc39be",
• "group_name": "my_group",
• "metadata": {

  • "description": "River 1 description",
  • "river_status": "active",
  • "current_version_id": "5f4d3b3d9f9c8b0001f6b0e6",
  • "created_by": "SomeUser",
  • "last_updated_by": "SomeUser",
  • "created_at": "2020-09-01T00:00:00Z",
  • "last_updated_at": "2020-09-01T12:00:00.000Z",
  • "is_deleted": false

  },
• "properties": {

  • "properties_type": "source_to_target",
  • "source": {

    • "name": "mysql",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "run_type": "predefined_report",
    • "cdc_settings": {

      • "default_tables_migration_option": "SKIP_INITIAL_MIGRATION",
      • "include_snapshot_tables": true,
      • "datasource_id": "mysql"

      },
    • "additional_settings": {

      • "extract_method": "all"

      },
    • "custom_query_source_settings": {

      • "query": "SELECT id, name FROM users WHERE active = true",
      • "array_size": 1000,
      • "exporter_chunk_size": 30000,
      • "incremental_type": "datetime",
      • "incremental_field": "created_at",
      • "date_range": {

        • "time_period": "custom",
        • "start_date": "2020-12-01T00:00:00.000Z",
        • "end_date": "2020-01-01T00:00:00.000Z",
        • "days_back": 1,
        • "include_end_value": true,
        • "split_time_intervals": {

          • "interval_size": 3,
          • "time_interval": "days"

          },
        • "update_increment_on_failures": true,
        • "utc_offset": -3,
        • "round_up": true

        },
      • "running_number": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": 1,
        • "end_value": 100

        },
      • "epoch": {

        • "start_value": 1727503847,
        • "end_value": 1727590247,
        • "include_end_value": true

        },
      • "row_version": {

        • "include_end_value": true,
        • "rows_in_chunk": 1000,
        • "start_value": "version",
        • "end_value": "version"

        },
      • "extract_method": "incremental"

      }

    },
  • "target": {

    • "name": "snowflake",
    • "connection_id": "5f4d3b3d9f9c8b0001f6b0e6",
    • "connection_name": "Connection 1",
    • "single_table_settings": {

      • "escape_character": "\\t",
      • "match_keys": [

        • "id",
        • "username"

        ],
      • "mapping": [

        • {

          • "name": "id",
          • "type": "INTEGER"

          }

        ],
      • "sql_dialect": "standard",
      • "split_tables": "no",
      • "split_data": "a>3",
      • "split_interval": "daily",
      • "partition_type": "TIMESTAMP",
      • "partition_granularity": "DAY",
      • "distribution_method": "even"

      },
    • "table_name": "Table 1",
    • "target_prefix": "start_at_",
    • "is_ordered_merge_key": true,
    • "order_expression": "id desc,createDate asc",
    • "loading_method": "merge",
    • "merge_method": "merge",
    • "file_zone_settings": {

      • "path": "my_path",
      • "bucket_name": "my_bucket",
      • "partitioned_kind": "by_day",
      • "fz_loading_mode": "auto-period"

      },
    • "file_path_destination": "path/to/file",
    • "additional_settings": {

      • "key": "value"

      },
    • "database_name": "Database 1",
    • "schema_name": "Schema 1"

    },
  • "schemas": [ ]

  },
• "settings": {

  • "run_timeout_seconds": 43200,
  • "notification": {

    • "warning": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "failure": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      },
    • "run_threshold": {

      • "email": "test@test.com",
      • "is_enabled": true,
      • "execution_time_limit_seconds": 43200

      }

    }

  },
• "schedulers": [ ]

}

Activate Data Flow

Authorization scope: data flow:write

This endpoint activates a data flow for allowing it to run.

---

📖 Instructions for usage

activate_data_flow

Activate (schedule) a data flow so it runs on its configured schedule.

Set wait=True to block until activation completes or fails — eliminates
the need to manually call get_operation in a loop.
Returns the final operation status when wait=True.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/activate_river

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/activate_river

Response samples

• 202
• 422

Content type

application/json

Example

OperationResponseResponse Activate RiverOperationResponse

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Disable Data Flow

Authorization scope: data flow:write

This endpoint disables a data flow to forbid it from running.

---

📖 Instructions for usage

disable_data_flow

Disable (pause) a data flow's schedule without deleting it.

Returns {"disabled": true, "data_flow_id": ...} (the upstream may return an empty body).

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/disable_river

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/disable_river

Response samples

• 202
• 422

Content type

application/json

Example

OperationResponseResponse Disable RiverOperationResponse

{

• "operation_id": "62e7f4352c13160013dc39be",
• "operation_type": "dataframe",
• "run_id": "5cbc6bbbc90a4658b00c70a3bb0f3b31",
• "last_update_date": "2022-08-02T13:38:44.054000",
• "status": "D",
• "result": "true",
• "error_message": "[RVR-QBK-003]: Response value error: Missing Rows/Columns"

}

Run Data Flow

Authorization scope: data flow:execute

This endpoint runs a data flow.

---

Throttling rules: *** Data Flow can be executed up to 2 times per minute** *** Each user can execute a data flow up to 15 times per minute**

---

📖 Instructions for usage

run_data_flow

Trigger an immediate run of a data flow.

By default returns instantly with the run_id (do NOT poll). Set wait=True to block
until the run reaches a terminal state (success/failed/cancelled) and return the
final run object — useful for tests/automation so you don't sleep blindly.

Before calling this, make sure ALL source tables are configured in a single
set_data_flow_source_tables call — one data flow syncs multiple tables in one run.

Common 400 causes:
  - Data flow not yet activated: call activate_data_flow(wait=True) first.
  - No source tables configured: call set_data_flow_source_tables first.

📚 Per-source request/response examples: https://bitbucket.org/boomii/data-integration-sources-examples/src/main/

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
river_cross_id required	string (River Cross Id)

query Parameters

run_sub_rivers

boolean (Run Sub Rivers) Default: false A flag that indicates whether to run all active sub rivers of the master river

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/run

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/rivers/{river_cross_id}/run

Response samples

• 202
• 422

Content type

application/json

{

• "runs": [

  • {

    • "sub_river_id": "62e7f4352c13160013dc39be",
    • "run_id": "1f1468d097754cd8892468c2763ebfe8",
    • "status": "pending",
    • "message": "The river is already in progress."

    }

  ],
• "river_cross_id": "string",
• "run_group_id": "string"

}

Environments

List Environments

Authorization scope: environment:list

Get list of environments entities for an account

---

📖 Instructions for usage

list_environments

List all environments for an account.

Authorizations:

HTTPBearer

path Parameters

account_id required

string (Account Id)

query Parameters

include_deleted	boolean (Include Deleted) Default: false
is_deployable_environments	boolean (Is Deployable Environments) Default: false
items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "items": [

  • {

    • "_id": "633ede20f1fc5500111fd7b3",
    • "account": "62e7f4352c13160013dc39be",
    • "user_created": "62e7f4352c13160013dc39be",
    • "created_at": "2022-07-25T18:38:55.640Z",
    • "cross_id": "62e7f4352c13160013dc39be",
    • "updated_at": "2022-08-02T13:38:44.054000",
    • "environment_name": "Dev Environment",
    • "color": "Gray",
    • "description": "Development environment for new rivers",
    • "variables": {

      • "aws_file_zone": "Rivery-rivery",
      • "azure_file_zone": "Rivery-rivery",
      • "days_ago": "0",
      • "gcs_file_zone": "Rivery-rivery",
      • "hours_offset": "0"

      },
    • "is_deleted": false,
    • "deleted_by": "62e7f4352c13160013dc39be",
    • "deleted_at": "2022-07-25T18:38:55.640Z",
    • "is_default": true,
    • "updated_by": "62e7f4352c13160013dc39be",
    • "is_delete_lock": true

    }

  ]

}

Connections

Get Connections

Authorization scope: connection:list

Get all connection entities as a paginated list

---

📖 Instructions for usage

list_connections

List all connections in an environment (sweeps every page in one call).

Returns {items, total_items, page, has_next}. Each item includes connection_name,
connection_type, connection_type_id, and cross_id; use cross_id as connection_id
when creating data flows. If the upstream 500s on a specific page, that page is
skipped and its number is reported under "incomplete_pages" rather than failing
the whole listing.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

query Parameters

items_per_page	integer (Items Per Page) [ 1 .. 500 ] Default: 20 The number of items per page in the paginated list.
page	integer (Page) >= 1 Default: 1 The current page number in the paginated list.

Responses

Response Schema: application/json

current_page_size required	integer (Current Page Size) The current page size
account_id required	string (Account Id) The account id
environment_id required	string (Environment Id) The environment id
required	Array of objects (Items)
	Next Page (string) or Next Page (null) (Next Page) The next page URL
	Previous Page (string) or Previous Page (null) (Previous Page) The previous page URL
page	integer (Page) Default: 1 The page number
total_items	integer (Total Items) Default: 0 The total number of entities fetched

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

Response samples

• 200
• 422

Content type

application/json

{

• "next_page": "string",
• "previous_page": "string",
• "page": 1,
• "current_page_size": 0,
• "total_items": 0,
• "account_id": "string",
• "environment_id": "string",
• "items": [

  • {

    • "account_id": "string",
    • "environment_id": "string",
    • "cross_id": "5f887c764c40e5598f717676",
    • "_id": "5f887c764c40e5598f717676",
    • "connection_name": "test connection",
    • "connection_type": "Oracle",
    • "connection_type_id": "oracle",
    • "is_test_connection": false,
    • "connection_update_by": "5f887c764c40e5598f717676",
    • "connection_update_time": "2019-08-24T14:15:22Z"

    }

  ]

}

Add Connection

Authorization scope: connection:edit

Creates a new connection entity.

---

📖 Instructions for usage

create_connection

Create a new connection. body must match the CreateConnection API schema.

NOT ALL CONNECTION TYPES CAN BE CREATED HERE. Connections that authenticate
via OAuth (e.g. Google services, Salesforce, HubSpot, Facebook/Meta, LinkedIn,
and similar — anything that needs a browser sign-in / "Connect with..." flow)
CANNOT be created through this tool, because OAuth requires an interactive
browser consent step. For those, tell the user:
"This connection uses OAuth — please create it in the Boomi Data Integration
console, then I can use it here."

This tool works for connections that authenticate with credentials you can
supply directly (host/port/user/password/keys), e.g. databases like mysql,
postgresql, mssql, snowflake, bigquery, redshift, mongodb.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Request Body schema: application/json

required

object (Connection To Create)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 201
• 422

Content type

application/json

{ }

Update Connection

Authorization scope: connection:edit

This endpoint updates a connection

---

📖 Instructions for usage

update_connection

Update an existing connection.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
cross_id required	string (Cross Id)

Request Body schema: application/json

required

object (Connection To Update)

Responses

Response Schema: application/json

object (Response Update Connection)

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{cross_id}

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 422

Content type

application/json

{ }

Delete Connection

Authorization scope: connection:delete

This endpoint deletes a connection

---

📖 Instructions for usage

delete_connection

Delete a connection.

The upstream DELETE returns an empty body on success; this returns
{"deleted": true, "connection_id": ...}.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)
connection_cross_id required	string (Connection Cross Id)

Responses

Response Schema: application/json

any

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{connection_cross_id}

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/connections/{connection_cross_id}

Response samples

• 200
• 422

Content type

application/json

null

Variables

List Variables

Authorization scope: variables:list

List variables

---

📖 Instructions for usage

list_variables

List all variables in an environment.

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Responses

Response Schema: application/json

variables required

object (Variables)

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

Response samples

• 200
• 422

Content type

application/json

{

• "variables": { }

}

Add Or Update Variables

Authorization scope: variables:edit

Add new variable or update existing one for environment

---

📖 Instructions for usage

upsert_variables

Create or update variables in an environment.

Each item in variables should be: {"name": "VAR_NAME", "value": "some_value"}.

Returns {"updated": true, "count": N} (the upstream may return an empty body).

Authorizations:

HTTPBearer

path Parameters

account_id required	string (Account Id)
environment_id required	string (Environment Id)

Request Body schema: application/json

required

variables required

object (Variables)

Responses

US

https://api.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

EU

https://api.eu-west-1.rivery.io/v1/accounts/{account_id}/environments/{environment_id}/variables

Request samples

• Payload

Content type

application/json

{

• "variables": { }

}

Response samples

• 201
• 422

Content type

application/json

{

• "variables": { }

}