From 86e3065a92dcc44a6119d2bd8c6899c7acefb7f3 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Thu, 9 Jul 2026 16:47:40 +0200 Subject: [PATCH 1/6] feat: add Cobuild support metadata --- custom-recipes/api-connect/Cobuild.md | 29 ++++++++++++++++++++++++++ custom-recipes/api-connect/recipe.json | 3 +++ 2 files changed, 32 insertions(+) create mode 100644 custom-recipes/api-connect/Cobuild.md diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md new file mode 100644 index 0000000..920478e --- /dev/null +++ b/custom-recipes/api-connect/Cobuild.md @@ -0,0 +1,29 @@ +# Cobuild guidance + +Use this recipe to call a REST API once for each row of the input dataset and write the extracted response to the output dataset. + +Roles: +- `input_A_role`: required input dataset containing the variables used in URL, header, query, body, and pagination templates. +- `api_output`: required output dataset for the API response rows. + +Core configuration: +- Set `endpoint_url` to the URL template. Dataset columns can be referenced as `{{column_name}}`. +- Set `http_method` to `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. +- Use `endpoint_query_string` for query parameters and `endpoint_headers` for headers. +- Use `parameter_columns` to expose input columns as template variables. +- Use `parameter_renamings` when column names should map to cleaner template variable names. +- Use `body_format`, `text_body`, or `key_value_body` for request bodies. `text_body` is visible for `RAW`; `key_value_body` is visible for `FORM_DATA` and `MULTIPART_FORM_DATA`. +- Set `extraction_key` when the response data is nested under a JSON key. Keep `raw_output=true` when the full response JSON should be kept. + +Authentication and presets: +- This recipe uses preset fields for credentials. Prefer an existing usable preset from the recipe definition. +- For the generic credential preset, keep `auth_type` null and set `credential` to the selected preset name from parameter set `credential`. +- For secure OAuth, set `auth_type=secure_oauth` and set `secure_oauth` to a preset from parameter set `secure-oauth`. +- For secure OAuth with refresh-token rotation, set `auth_type=secure_oauth_refresh_token_rotation` and set `secure_oauth_refresh_token_rotation` to a preset from parameter set `secure-oauth-refresh-token-rotation`. +- For secure basic auth, set `auth_type=secure_basic` and set `secure_basic` to a preset from parameter set `secure-basic`. +- Do not ask the user to paste preset secrets in chat. If no usable preset is available or selected, create the recipe skeleton, navigate to the recipe settings, and ask the user to select or create the preset there. + +Pagination: +- Keep `pagination_type=na` unless the API documentation requires pagination. +- For next-page pagination, set `next_page_url_key`, and set `is_next_page_url_relative` plus `next_page_url_base` when the returned next URL is relative. +- For offset or page pagination, set the visible key fields and define `extraction_key` when required by the API response shape. diff --git a/custom-recipes/api-connect/recipe.json b/custom-recipes/api-connect/recipe.json index f836ed9..c4793de 100644 --- a/custom-recipes/api-connect/recipe.json +++ b/custom-recipes/api-connect/recipe.json @@ -5,6 +5,9 @@ "icon": "icon-rocket" }, "kind": "PYTHON", + "cobuild": { + "supported": true + }, "selectableFromDataset": "input_A_role", "inputRoles": [ { From 1059ff61ebd0f2f0f0c59bee0f144271f1e7f291 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 21 Jul 2026 15:19:52 +0200 Subject: [PATCH 2/6] chore: streamline Cobuild guidance --- custom-recipes/api-connect/Cobuild.md | 38 +++++++++++---------------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 920478e..b9c5bd4 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,29 +1,21 @@ # Cobuild guidance -Use this recipe to call a REST API once for each row of the input dataset and write the extracted response to the output dataset. +Role-specific behavior: +- `input_A_role` supplies one API call per row and the column values available to request templates. +- `api_output` collects the response rows extracted from those calls and any paginated responses. -Roles: -- `input_A_role`: required input dataset containing the variables used in URL, header, query, body, and pagination templates. -- `api_output`: required output dataset for the API response rows. +Request behavior: +- Columns selected in `parameter_columns` become `{{column_name}}` template variables across the URL, headers, query parameters, body, and pagination settings; `parameter_renamings` changes their template names. +- `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. +- `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. +- `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. -Core configuration: -- Set `endpoint_url` to the URL template. Dataset columns can be referenced as `{{column_name}}`. -- Set `http_method` to `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. -- Use `endpoint_query_string` for query parameters and `endpoint_headers` for headers. -- Use `parameter_columns` to expose input columns as template variables. -- Use `parameter_renamings` when column names should map to cleaner template variable names. -- Use `body_format`, `text_body`, or `key_value_body` for request bodies. `text_body` is visible for `RAW`; `key_value_body` is visible for `FORM_DATA` and `MULTIPART_FORM_DATA`. -- Set `extraction_key` when the response data is nested under a JSON key. Keep `raw_output=true` when the full response JSON should be kept. - -Authentication and presets: -- This recipe uses preset fields for credentials. Prefer an existing usable preset from the recipe definition. -- For the generic credential preset, keep `auth_type` null and set `credential` to the selected preset name from parameter set `credential`. -- For secure OAuth, set `auth_type=secure_oauth` and set `secure_oauth` to a preset from parameter set `secure-oauth`. -- For secure OAuth with refresh-token rotation, set `auth_type=secure_oauth_refresh_token_rotation` and set `secure_oauth_refresh_token_rotation` to a preset from parameter set `secure-oauth-refresh-token-rotation`. -- For secure basic auth, set `auth_type=secure_basic` and set `secure_basic` to a preset from parameter set `secure-basic`. -- Do not ask the user to paste preset secrets in chat. If no usable preset is available or selected, create the recipe skeleton, navigate to the recipe settings, and ask the user to select or create the preset there. +Response extraction: +- Use the dot-separated `extraction_key` when response rows are nested under a JSON path. +- Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. Pagination: -- Keep `pagination_type=na` unless the API documentation requires pagination. -- For next-page pagination, set `next_page_url_key`, and set `is_next_page_url_relative` plus `next_page_url_base` when the returned next URL is relative. -- For offset or page pagination, set the visible key fields and define `extraction_key` when required by the API response shape. +- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. +- For next-page pagination, `next_page_url_key` is the dot-separated response path containing the following request URL. When that URL is relative, enable `is_next_page_url_relative` and provide `next_page_url_base`. +- Page pagination requires `extraction_key` so the recipe can locate and count the returned data array. +- For offset and page pagination, `skip_key` is the query parameter carrying the next offset or page number. From 345e25d82401653579f5cc685fab6b34a6ffdca1 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Wed, 22 Jul 2026 15:17:11 +0200 Subject: [PATCH 3/6] chore: document automatic API key injection --- custom-recipes/api-connect/Cobuild.md | 1 + 1 file changed, 1 insertion(+) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index b9c5bd4..24b96bb 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -9,6 +9,7 @@ Request behavior: - `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. - `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. - `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. +- For API-key presets, API Connect automatically injects the key into either a request header or query parameter, as configured by the user in the preset. Response extraction: - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. From b3e5bf491cd060df61ac888dd83e6630256adff7 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 09:04:40 +0200 Subject: [PATCH 4/6] chore: refine API Connect Cobuild guidance --- custom-recipes/api-connect/Cobuild.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 24b96bb..80f99f1 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,22 +1,9 @@ # Cobuild guidance -Role-specific behavior: -- `input_A_role` supplies one API call per row and the column values available to request templates. -- `api_output` collects the response rows extracted from those calls and any paginated responses. - -Request behavior: -- Columns selected in `parameter_columns` become `{{column_name}}` template variables across the URL, headers, query parameters, body, and pagination settings; `parameter_renamings` changes their template names. -- `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. -- `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. -- `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. -- For API-key presets, API Connect automatically injects the key into either a request header or query parameter, as configured by the user in the preset. - -Response extraction: +- API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. +- Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. +- With `auth_type=null`, leave `credential` unset for an unauthenticated API; otherwise select a compatible generic credential preset. For a secure authentication type, select its corresponding visible preset. +- API Connect automatically injects an API-key preset into the header or query parameter configured by the user in that preset. Do not add the API key again to request fields. - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. - Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. - -Pagination: -- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. -- For next-page pagination, `next_page_url_key` is the dot-separated response path containing the following request URL. When that URL is relative, enable `is_next_page_url_relative` and provide `next_page_url_base`. -- Page pagination requires `extraction_key` so the recipe can locate and count the returned data array. -- For offset and page pagination, `skip_key` is the query parameter carrying the next offset or page number. +- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. Relative next-page URLs require `next_page_url_base`, page pagination requires `extraction_key`, and offset or page pagination requires `skip_key`. From 7d13e75f7d9f304960ae03dc02a544c96e24572f Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 09:13:40 +0200 Subject: [PATCH 5/6] chore: clarify API Connect preset guidance --- custom-recipes/api-connect/Cobuild.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 80f99f1..c6d9d78 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -2,7 +2,7 @@ - API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. - Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. -- With `auth_type=null`, leave `credential` unset for an unauthenticated API; otherwise select a compatible generic credential preset. For a secure authentication type, select its corresponding visible preset. +- `auth_type=null` supports either no authentication (`credential` unset) or a generic credential preset. A secure authentication type requires its corresponding visible preset. - API Connect automatically injects an API-key preset into the header or query parameter configured by the user in that preset. Do not add the API key again to request fields. - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. - Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. From ecb49f1b5e20daa058b27bb0b60faf8afa21b7d1 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 10:39:50 +0200 Subject: [PATCH 6/6] chore: remove redundant Cobuild header --- custom-recipes/api-connect/Cobuild.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index c6d9d78..5685154 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,5 +1,3 @@ -# Cobuild guidance - - API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. - Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. - `auth_type=null` supports either no authentication (`credential` unset) or a generic credential preset. A secure authentication type requires its corresponding visible preset.