Keboola

Retrieves detailed information about one or more components by their IDs. RETURNS FOR EACH COMPONENT: - Component metadata (name, type, description) - Documentation and usage instructions - Configuration JSON schema (required for creating/updating configurations) - Links to component dashboard in Keboola UI Components that cannot be retrieved are listed in `not_found` (missing) or `errors` (server-side, retryable); the call fails only if none of them can be retrieved. WHEN TO USE: - Before creating a new configuration: fetch the component to get its configuration schema - Before updating a …

Retrieves sample configuration examples for a specific component. USAGE: - Use before calling `create_config` or `add_config_row` to understand the expected parameters structure. - Use when you want to see example configurations for a specific component. EXAMPLES: - user_input: `Show me example configurations for component X` - set the component_id parameter accordingly - returns a markdown formatted string with configuration examples

Retrieves component configurations in the project with optional filtering. Can list summaries of multiple configurations (grouped by component) or retrieve full details for specific configurations. Returns a list of components, each containing: - Component metadata (ID, name, type, description) - Configurations for that component (summaries by default, full details if requested) - Links to the Keboola UI PARAMETER BEHAVIOR: - If configs is provided (non-empty): Returns FULL details ONLY for those configs. Configs that cannot be retrieved are listed in `not_found` (missing) or `errors` (se…

Creates a short-lived link that opens a dev-mode data app in your browser without the app's login. Use it to see or test a python-js **draft** deployed with `deploy_data_app(action='deploy', mode='dev')`. - Only a python-js draft reaches dev mode: a Streamlit app has no managed git repo and its image has no dev mode. - An app that is not in dev mode has no preview link. ## How to use the link - Open `url` in a real browser before `link_expires_at` (about 60 seconds after this call): a browser tool, or a headless browser CLI run from your shell. Do not fetch it with an HTTP client or curl…

Lists summaries of data apps in the project given the limit and offset or gets details of a data apps by providing their configuration IDs. WHEN NOT TO USE: - Do NOT list all data apps just to find one by name. Use `search` with item_types=["data-app"] instead. - Only list all data apps when you need a complete inventory. Considerations: - If configuration_ids are provided, the tool will return details of the data apps by their configuration IDs. - If no configuration_ids are provided, the tool will list all data apps in the project given the limit and offset. - Data App detail contains co…

Retrieves examples of valid flow configurations. PRE-REQUISITES: - Unknown examples for the target flow type: `keboola.flow` (conditional) or `keboola.orchestrator` (legacy) to help build the specific flow configuration by mirroring the structure/fields. RULES: - Conditional-flow examples require conditional flows to be enabled; otherwise use legacy orchestrator examples - Present the examples or cite unavailability to the user

Returns the JSON schema for the given flow type (markdown). PRE-REQUISITES: - Unknown schema for the target flow type: `keboola.flow` (conditional) or `keboola.orchestrator` (legacy) RULES: - Projects without conditional flows enabled cannot request `keboola.flow` schema - Use the returned schema to shape `phases` and `tasks` for `create_flow` / `create_conditional_flow` / `update_flow`

Lists flows or retrieves full details for specific flows. WHEN NOT TO USE: - Do NOT call with `flow_ids=[]` just to find a flow by name. Use `search` with item_types=["flow"] instead. - Only use `flow_ids=[]` when you need a complete list of all flows in the project. OPTIONS: - `flow_ids=[]` → summaries of all flows in the project - `flow_ids=["id1", ...]` → full details (including phases/tasks) for those flows; flows that cannot be retrieved are listed in `not_found` (missing) or `errors` (server-side, retryable), and the call fails only if none of them can be retrieved; a flow whose …

Retrieves job execution information from the Keboola project. CONTEXT: Jobs in Keboola are execution records of components (extractors, transformations, writers, flows). Each job represents a single run with its status, timing, configuration, and results. TWO MODES OF OPERATION (controlled by job_ids parameter): MODE 1: GET DETAILS FOR SPECIFIC JOBS (job_ids is non-empty) - Provide one or more job IDs: job_ids=["12345", "67890"] - Returns: FULL details for each job including status, config_data, results, timing, and metadata - Jobs that cannot be retrieved are listed in `not_found` (missing…

Retrieves structured information about the current project, including essential context and base instructions for working with it (e.g., transformations, components, workflows, and dependencies). Always call this tool at least once at the start of a conversation to establish the project context before using other tools. Reports on exactly one project; pass `project_id` to pick which when the session is scoped to 2+ projects.

Loads semantic objects grouped by semantic object type. CONSIDERATIONS: - If a selection has empty `ids`, the tool returns all objects of that type in compact form. - If a selection has non-empty `ids`, the tool returns only those specific objects with full attributes. - `semantic_model_ids` optionally narrows the lookup to specific semantic models. - An object returned here carries `scope` ("project", "organization", or "targeted"), `project_id` (the project it was created in -- present regardless of scope), `source_project_id` (which project an "organization"-scope object came from, if …

Returns JSON schemas for the requested semantic object types. WHEN TO USE: - When you want to know the JSON schema of a semantic object type, e.g. before searching something specific.

Lists buckets shared with this project by other Keboola projects that are not necessarily linked into this project yet (the Data Catalog "Shared with me" view). Use this to answer "what data is shared with this project?" or "what could I link?" — `get_buckets` only returns buckets already in this project (including already-linked ones). Results are paginated (`limit`/`offset`) because the number of shared buckets can be large for projects in big organizations — always check `total_count` and the `message` to see whether more results exist, and page through with `offset` rather than assuming a…

Retrieves the Data Streams in the project: sources receiving events and the sinks writing them to tables. Data Streams receive events over HTTP (webhooks, apps) or OTLP (OpenTelemetry logs/metrics/traces) and store them in Storage tables in near real time, without any component configuration. Each stream includes its `endpoint_url` (with the secret embedded) and, for OTLP, `otlp_base_url` plus `otlp_secret`. Give these only to the user who asked; they authenticate writes into the project. Sessions with read-only access get them hidden (`secret_redacted=true`). If Data Streams are not enable…

Lists tables in buckets or retrieves full details of specific tables, including fully qualified database name, column definitions, lineage references (created/updated by) and links. WHEN NOT TO USE: - Do NOT list tables across buckets just to find a table by name. Use `search` with item_types=["table"] instead — it also matches column names and descriptions. - Only use `bucket_ids` listing when you need all tables in specific known buckets. RETURNS: - With `bucket_ids`: Summaries of tables (ID, name, description, primary key). - With `table_ids`: Full details including columns, data types,…

Links a bucket shared with this project (found via `get_shared_buckets`) into this project as a new local bucket, so its tables become directly queryable/joinable like any other bucket in the project. Not idempotent: calling this again with the same `target_bucket_name` fails once that name already exists, so don't retry blindly on error without checking whether the link succeeded. Note: unlike `get_buckets`, the returned bucket does not participate in this server's prod/dev branch-shading (its `branch_id` is not resolved) -- linking always targets the caller's current branch context directl…

Updates an existing flow configuration (either legacy `keboola.orchestrator` or conditional `keboola.flow`) or manages schedules for this flow. PRE-REQUISITES: - Always use `get_flow_schema` (and `get_flow_examples`) for that flow type you want to update to follow the required structure and see the examples if unknown - Only pass `phases`/`tasks` when you want to replace them; omit to keep the existing ones unchanged RULES (ALL FLOWS): - `flow_type` must match the stored component id of the flow; do not switch flow types during update - `phases` and `tasks` must follow the schema for the sel…

Creates or updates a python-js data app. Python-js is the default type for new data apps when you can run git: this tool only creates the configuration and the repository, and you deliver the source code by `git push`. Use `modify_streamlit_data_app` instead when you cannot run git or when the user asks for Streamlit explicitly. Two-app project model. Every python-js project has a persistent **prod app** that owns the only managed git repository for the project, and zero or more **drafts** parented to that prod app. A draft is a Storage configuration with `parameters.dataApp.isDraft=true` an…

Creates or updates a Streamlit data app. <!-- directory:omit --> Python-js is the default type for new data apps when you can run git: create them with `modify_python_js_data_app` (python-js source code is delivered only by `git push`). Use this tool to create a new app when you cannot run git or when the user asks for Streamlit explicitly, and to update existing Streamlit apps. <!-- /directory:omit --> <!-- directory:only --> Use this tool to create new data apps and to update existing Streamlit apps. Other data apps cannot be changed here; tell the user so. <!-- /directory:only --> Conside…

Executes an SQL SELECT query to get the data from the underlying database. Only one read-only statement is accepted: SELECT or WITH ... SELECT, and on Snowflake also SHOW, DESCRIBE or EXPLAIN (BigQuery has none of these; query INFORMATION_SCHEMA instead). Anything else, including multiple statements, is rejected before it reaches the database. BEFORE QUERYING: * Always verify the table has a non-null fullyQualifiedName from get_tables tool. If it does not, the table is not SQL-accessible from this workspace — do not attempt the query and inform user. CRITICAL SQL REQUIREMENTS: * ALWAYS ch…

Starts a new job for a given component or transformation.

Executes a synchronous action for a component configuration or a component row configuration. Effects depend on the component and action; execution can modify external resources. WHEN TO USE: - For finding available values of a configuration field - For validating already configured values (e.g. testing a database connection) - For listing remote resources such as endpoints, schemas or tables

Searches for Keboola items (tables, buckets, components, configurations, transformations, flows, data-apps, etc.) in the current project and returns matching ID + metadata. This tool supports two complementary search types: 1) textual - Searches items by name, server-side (fast, independent of project size). - Tokenized full-text name matching, case- and diacritics-insensitive. Pass the plain name; do NOT build regex (rejected). It is NOT typo-corrected — misspellings may not match. - Prefers the current branch context; when nothing is found there, automatically widens the search to all …

Searches semantic models and semantic objects using regex patterns matched against their names, descriptions and stringified JSON attributes. Returns compact matches grouped by semantic model. Each match includes the semantic object type, the paths where the patterns matched, and compact object view. CONSIDERATIONS: - The search is case-insensitive by default. Use `case_sensitive=True` when exact casing matters. - The search is performed against semantic object names and data attributes which are stringified JSON objects following their corresponding JSON schema. - The search can be scoped t…

Scopes the current session to a set of Keboola projects. Mints a scoped access token (narrowed to `project_ids`, optionally read-only) that is used for the rest of the conversation. Read-only tools then run against every scoped project in a single call; write/modify/delete tools take a `project_id` argument naming which scoped project to target (required once 2+ projects are scoped). Call this when the user states which projects to work on; it can be called again any time to re-scope. On most transports the server does not remember this scope between calls: pass the returned `scope_token` as…

Updates an existing root component configuration by modifying its parameters, storage mappings, name or description. Not for SQL transformations (`keboola.snowflake-transformation` / `keboola.google-bigquery-transformation`), data apps (`keboola.data-apps`) or flows — use the dedicated tools (see WHEN NOT TO USE). This IS the tool for updating Python (`keboola.python-transformation-v2`), R (`keboola.r-transformation-v2`) and DuckDB (`keboola.duckdb-transformation`) transformations. This tool allows PARTIAL parameter updates - you only need to provide the fields you want to change. All other f…

Updates an existing component configuration row by modifying its parameters, storage mappings, name, or description. This tool allows PARTIAL parameter updates - you only need to provide the fields you want to change. All other fields will remain unchanged. Configuration rows are individual items within a configuration, often representing separate data sources, tables, or endpoints that share the same component type and parent configuration settings. WHEN TO USE: - Modifying row-specific parameters (table sources, filters, credentials, etc.) - Updating storage mappings for a specific row (in…

Updates the description for a Keboola storage item. This tool supports three item types, inferred from the provided item_id: - bucket: item_id = "in.c-bucket" - table: item_id = "in.c-bucket.table" - column: item_id = "in.c-bucket.table.column" Usage examples (payload uses a list of DescriptionUpdate objects): - Update a bucket: updates=[DescriptionUpdate(item_id="in.c-my-bucket", description="New bucket description")] - Update a table: updates=[DescriptionUpdate(item_id="in.c-my-bucket.my-table", description="New table description")] - Update a column: updates=[DescriptionUpdate(item…

Updates an existing flow configuration (either legacy `keboola.orchestrator` or conditional `keboola.flow`). PRE-REQUISITES: - Always use `get_flow_schema` (and `get_flow_examples`) for that flow type you want to update to follow the required structure and see the examples if unknown - Only pass `phases`/`tasks` when you want to replace them; omit to keep the existing ones unchanged RULES (ALL FLOWS): - `flow_type` must match the stored component id of the flow; do not switch flow types during update - `phases` and `tasks` must follow the schema for the selected flow type; include at least `…

Updates the description of the current Keboola project.

Updates an existing SQL transformation configuration by modifying its SQL code, storage mappings, name or description. This tool allows PARTIAL parameter updates for transformation SQL blocks and code - you only need to provide the operations you want to perform. All other fields will remain unchanged. Use this for modifying SQL transformations created with create_sql_transformation. WHEN TO USE: - SQL transformations only (Snowflake/BigQuery); use update_config for Python/R/DuckDB transformations - Modifying SQL queries in transformation (add/edit/remove SQL statements) - Updating transform…

Performs best-effort semantic validation of an SQL query against one or more semantic models and compares it with the expected semantic objects provided. RETURNS: - `validation_auto_detected`: semantic validation built from objects heuristically detected in the SQL - `validation_detected_from_expected`: semantic validation built only from explicitly provided expected object IDs - expected semantic objects that were matched or missing in the auto-detected result - unexpected auto-detected objects outside the expected semantic scope LIMITATIONS: - Detection is heuristic and based on string mat…