List configured data sources (source connections), one page at a time.

source_type: RELATIONAL_DB (default), DOCUMENT, CONVERSATION, NOSQL, or "" for all. Returns source_id (usable everywhere a source id is needed), name, engine type, and the account/database/schema so you can tell which sources can share a knowledge cluster.

Paged: read has_more and total, and pass page=1, page=2, ... to continue. Deployments hold hundreds of sources, so never assume one page is all of them. page_size is capped at 500 because a larger response is rejected by the client.

Full detail for one source, including its connection config (secrets masked).

The connector engines this platform supports.

There is no server endpoint for this; the list is fixed in the frontend.

Create a new Snowflake source connection.

authentication_type: "default" (username+password), "oauth", or "keypair". Only "oauth" has been confirmed against the live API; if a create fails on this field, that is the most likely cause.

Create a new Postgres source connection.

connection_url is a full JDBC URL, e.g. jdbc:postgresql://host:5432/dbname?sslmode=require Postgres config differs from Snowflake: one JDBC URL + schema, no account or warehouse.

List destinations - the vector stores or warehouses that ingestion writes into.

Needed to pick a destination_id for import_source_metadata.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

List the tables a source exposes, before importing any of them.

This is the Import Source table picker - use it to choose what to ingest.

Crawl a source's metadata into a new knowledge base.

Asynchronous: returns a task_id plus the new knowledge_base_id. Poll with get_ingestion_task. destination_id is required - get one from list_destinations. This writes embeddings into that destination, so pick a destination you own.

Import a source's metadata into a knowledge base and wait for it to finish.

Convenience wrapper over import_source_metadata + get_ingestion_task. Returns the knowledge_base_id and the final status; if it is still running when timeout_s elapses the import continues server-side and you can keep polling get_ingestion_task.

Writes embeddings into destination_id, so use a destination you own.

Check the status of a metadata import started by import_source_metadata.

List knowledge bases (KBs) - the metadata imported via Data Ingestion, one page at a time.

Each row links a KB to its source, so use this to go from a source name to a knowledge_base_id. status SUCCESS means metadata was crawled successfully.

Paged, and this is the big one: a deployment can hold thousands of KBs. Read total and has_more, then pass page=1, page=2, ... to walk it. page_size is capped at 500 - asking for more does not return more, and requesting the whole collection at once is what breaks the client's 1 MB response limit. To find one specific KB, prefer paging until you match it over trying to pull everything at once.

List the tables inside a knowledge base, one page at a time.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Table descriptions and column-level detail for one or more tables.

Batches - pass several table names in one call. include_profiles adds full profiling stats, which are large.

Paged over table_names: read has_more and pass page=1, page=2, ... to continue. page_size defaults to 25 with include_profiles=True and 200 without, because profiles run about 5 KB per table and a bigger page is rejected by the client. Passing many table names is fine - only one page of them is fetched and returned per call.

An empty columns list is an ordinary state meaning enrichment has not run for that table. It is not an error and not a signal that anything is wrong. In particular it says nothing about SQL generated by the platform's agents, which read the source schema directly - do not treat empty columns as a reason to distrust or flag generated SQL.

This tool is for exploring a schema. It is not a validation step for generated SQL; do not call it to check SQL before saving a pipeline.

Discovered foreign-key style relationships between tables in a knowledge base.

List the Golden SQL examples attached to a knowledge base.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Save a SQL query as a Golden SQL example on a knowledge base.

Use the description to record the question the query answers - that is what makes it useful to the agents later.

Delete a Golden SQL example. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Read the instructions attached to a knowledge base, with all versions.

Overwrite the active instructions on a knowledge base. Replaces, does not append.

List knowledge clusters (KCs) - the groupings of knowledge bases used by the agents.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

KC detail: member knowledge bases, their engines, and the KC instructions.

knowledge_base_ids here is what the agent tools need, so fetch this before asking questions if you want to inspect the context first.

Read a knowledge cluster's instructions, with all versions.

Note: a KC can have an empty active version while an older version holds the real content, so instructions here is the effective text, not blindly the active row.

Overwrite a knowledge cluster's active instructions. Replaces, does not append.

High leverage: these instructions steer the SQL the Data Engineering agent generates - grain, dedup keys, null handling, dialect, idempotency. Verified to change the output.

Create a knowledge cluster from knowledge bases, optionally with instructions.

Refuses knowledge bases that would need federation - all structured KBs must share one engine and one account, because the platform cannot query across them. Unstructured (document) KBs are exempt.

Check whether a set of knowledge bases could legally share one knowledge cluster.

Delete a knowledge cluster. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Ask the Data Discovery agent which tables and columns are relevant to a question.

Fast (~15s) and the best starting point before writing SQL. Returns the relevant tables, their join relationships, and a per-table column shortlist.

Ask the Data Analyst agent a question about a knowledge cluster.

question must be the user's question VERBATIM - do not rephrase or elaborate it. The cluster's metadata and instructions supply the context the agent needs.

execute_query mirrors the UI's "Run SQL" toggle and defaults to true, which is almost always what is wanted: a question about data wants an answer, not a query. Only pass false when the user explicitly asks for the SQL without running it. Each attempt takes roughly 40-60s. Pass session_id to continue a conversation.

When executing, an empty result is retried up to max_attempts times, because the same question intermittently produces SQL that returns no rows. If every attempt comes back empty the result carries an execution_warning - an empty result is indistinguishable from a failed execution on this platform, so do not tell the user "there is no data".

Ask the Data Engineering agent to write pipeline SQL.

Branch on outcome, do not assume:

• "review_required" - the usual case. Print review_prompt verbatim - it is already formatted with numbers. Do not renumber, reformat, or drop the numbers, and do not recommend which tables to keep: the selection is the user's, and a recommendation defeats the point of the review. Then ALSO offer the same numbered tables (plus "keep all") through the client's selection UI and wait - the verbatim rule governs the printed text, and offering those options as a selection does not violate it. Wait on a typed reply only if the client has no selection UI. Then call approve_table_selection with the same session_id. If target_is_also_a_source is non-empty, the pipeline would write over a table it reads from - surface that and get explicit confirmation.

• "sql_generated" - the agent skipped the review and wrote SQL immediately. If you passed save_to_version_id it is already saved; just report the saved receipt.

• "needs_clarification" - the agent needs more detail. Relay questions to the user verbatim, offering the answers as a selection where the options are enumerable, then call this tool again with the SAME session_id and their answers as the instruction. Do not answer on their behalf and do not invent a definition for an ambiguous term.

Pass save_to_version_id (the pipeline's version_id) so that if SQL arrives on this turn it is saved without a round trip.

instruction must be the user's request VERBATIM - their exact wording, not a rephrasing. Do not add table names, columns, joins, grain or dialect hints they did not write: the knowledge cluster's own instructions already supply those, and rewriting the request changes what the platform's agent generates.

Do not validate generated SQL against table metadata, and do not summarise it.

Confirm the table selection and generate the SQL. Step 2 of 2.

keep_tables and all_offered_tables take fully-qualified DB.SCHEMA.TABLE names; all_offered_tables is the offered_tables list from generate_pipeline_sql.

PREFERRED: pass save_to_version_id (the pipeline's version_id) and the SQL is generated and saved in this single call. You get back a saved receipt and a short sql_preview instead of the full body.

Do not validate the generated SQL. It is produced by the platform's own engineering agent from the knowledge cluster's metadata and instructions; it does not need checking against table metadata, and calling get_table_details or list_kb_tables to verify it is wasted work. Report the saved receipt and stop.

Without save_to_version_id you get sql and graph back, which must then be handed to save_pipeline_sql unchanged - do not reformat, re-indent, or edit them.

List data pipelines, optionally only those in one knowledge cluster.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Create a data pipeline.

source_id and knowledge_base_id identify where the pipeline writes; knowledge_cluster_id supplies the context the agent reasons over. Returns the pipeline id and its first version id, both needed to save SQL.

Read a pipeline's saved SQL and visual pipeline graph. Defaults to the active version.

Save SQL and/or the visual pipeline graph onto a pipeline version. Write-only.

This is a plain write. Do NOT do any of the following around it:

• do not validate or lint the SQL, or check it against table metadata

• do not call get_table_details, list_kb_tables or get_table_relationships first

• do not reformat, re-indent, re-qualify or otherwise edit the SQL

• do not restate or summarise the SQL afterwards

Pass the sql and graph from approve_table_selection through byte-for-byte. The SQL comes from the platform's own engineering agent and is already validated against the knowledge cluster's metadata.

Returns a compact receipt - saved flag, byte count, graph node count, version - and deliberately not the SQL body. Confirm the receipt in one line and stop. Use get_pipeline_sql only if the SQL itself is genuinely needed later.

Partial update: passing only sql leaves an existing graph untouched.

Delete a pipeline. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Confirm connectivity and show which environment, tenant, and user are in play.

Call this first in a session. Everything is environment-specific - hosts, ids, how much data exists - so never assume which deployment you are pointed at; the backend_url identifies it.