The latest Genie documentation reads best as a stack rather than a loose set of features. At the bottom, Databricks exposes Genie Agents through two distinct sets of APIs. At the top, Genie One gives users a document surface that turns a good answer into something they can edit and share. In between sit validation rules, curation guidance, and operational limits, all of which make the whole thing deployable. You can embed Genie in your own applications, manage it like a deployable asset, and turn its output into a document without asking anyone to leave the interface.
💡 One naming note before the detail. Genie Spaces are now referred to as Genie Agents.
The API page states that Genie Agents were formerly known as Genie Spaces, and the endpoints still live under the /api/2.0/genie/spaces/ path. If you last read this documentation a few months ago, the concepts carry straight over.
Two APIs, two jobs
The API split matters more than it first appears. The Conversation APIs are the runtime layer. The docs describe them as natural language data querying with stateful conversations, where users ask follow-up questions and explore data naturally over time. The Management APIs are the lifecycle layer. They enable programmatic creation, configuration, and deployment of Genie Agents across workspaces, and the docs explicitly call out CI/CD pipelines, version control, and automated agent management.
That distinction fixes a common gap in enterprise AI products. Many tools can answer a question in a demo. Fewer give you a clean separation between runtime usage and change management. One set of endpoints allows an application to ask questions of a curated agent. Another set lets a platform team treat that agent as a configuration that can be created, updated, promoted, and backed up. That is the difference between an interesting interface and an operational surface.
The API is only as good as the agent behind it
Before calling the conversation endpoints, you must prepare a well-curated Genie Agent, because the agent provides the context Genie uses to interpret questions and generate answers. An incomplete or untested agent can still produce incorrect results even when the API integration is correct. That is an important correction to the usual instinct that the API wrapper is the hard part. In Genie, semantic preparation is part of the product.
The guidance is specific. A strong agent uses well-annotated Unity Catalog data with clear table and column comments. It is user tested with the questions you expect from real end users. It includes company-specific context such as instructions, example SQL, and functions. There are at least five tested example SQL queries, and at least five benchmark questions based on anticipated user asks. The API story begins with curation. If the agent is weak, the application layer inherits that weakness.
The runtime flow
The flow itself is straightforward, which is part of the appeal. You start a conversation against an agent, submit a question, and receive conversation and message objects. You then poll the message endpoint to track generation status and retrieve the generated SQL, and you use attachment identifiers to fetch the query results. Three details stand out for anyone building a real product on top of this.
Trusted assets are visible in the response. Check the attachments field for an
query.parametersobject. Its presence indicates the answer came from a trusted asset. Reasoning traces are exposed throughquery_attachmentsobjects when available. These are the hooks a serious team needs for explainability and front-end behaviour.Visualizations are optional and explicit. By default, the API returns tabular results. Set
enable_visualizationtotrueWhen starting a conversation or creating a message to receive visualization output in the attachments field. This capability as Beta.Useful content arrives before COMPLETED. The
COMPLETEDstatus means the reply process has finished, and polling can stop, but meaningful content is available earlier if your client inspects the response during polling rather than waiting for completion.
The two-phase caveat
There is one boundary worth knowing before you promise UI parity to anyone. The docs state that, unlike the Genie Agents UI, the Conversation API does not support the two-phase response pattern where Genie shows a preliminary answer and then updates it after inspection. If you want incremental progress in your own product, you implement it yourself by inspecting the attachments field while the message is still in intermediate states, such as PENDING_WAREHOUSE (or) EXECUTING_QUERY. That kind of detail is why this documentation feels operational rather than promotional. It tells you where the product boundary actually is.
Where the CI/CD story becomes concrete
The Management API side turns a Genie Agent into something you can move between environments. Retrieve an agent with include_serialized_space set to true and the serialized_space field returns the full serialised representation, including instructions, benchmarks, joins, and other configuration details. The docs make it plain that you can use this representation with the create and update APIs to promote Genie Agents across workspaces or to create backups of agent configurations. An agent stops being only a UI object. It becomes a configuration you can review, diff, version, and reproduce.
Strict validation is what makes pipelines viable
The configuration is not loose or forgiving. Invalid JSON is rejected during agent creation or update, and the rules are specific. These are the formats expected out of each field:
The
versionfield is required, and new agents use version 2.All ID fields must be 32-character lowercase hexadecimal strings in UUID format, without hyphens. Too short, uppercase, or hyphenated IDs are all rejected.
Collections containing identifiers must be pre-sorted. The system validates that arrays are already sorted and rejects unsorted input, and it documents sort keys for tables, metric views, column configs, and other collections.
Join specs have an exact shape. The sql field requires exactly two elements: the join condition with backtick-quoted alias references and a relationship type annotation such as "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--".
The docs even include a snippet for generating time-ordered UUIDs, so that IDs created in sequence sort alphabetically and automatically satisfy the sorting requirements. The strictness is what makes CI/CD viable. If an agent is going to live in source control and move across environments, the platform needs deterministic rules, and deterministic rules are what make diffs meaningful during promotion.
The platform guardrails
The data behind an agent must be registered in Unity Catalog. An agent can include up to 30 tables or views. Genie Agents require a pro or serverless SQL warehouse, and the author needs at least CAN USE permission on it. The author's compute credentials are embedded into the agent and used to process all queries for all users, which is worth understanding before you turn an agent into a shared service. Capacity is documented, too. Each agent supports up to 10,000 conversations, and each conversation can include up to 10,000 messages.
The operational guidance reads the same way. The API does not retry failed requests for you, so the docs tell you to implement retry logic with exponential backoff and your own queuing. They recommend comprehensive logging of requests and responses for debugging, usage monitoring, and cost tracking. They suggest polling every 1 to 5 seconds, limiting polling to 10 minutes for most queries, and returning a timeout or prompting a manual status check after that. This is documentation for a system that is expected to be embedded and monitored under real load.
The top of the stack: documents
Then there is the final layer, and it is easy to overlook that piece. Documents in Genie One are a workflow feature rather than an API feature. They matter because they close the loop between answer generation and team communication. The docs say Documents in Genie One let users turn chat responses into shareable, editable documents without leaving the interface. A user asks Genie One to draft a document, or clicks Draft a document in chat. The result opens in a canvas pane next to the conversation, where it can be edited with the toolbar and shared with users, groups, or service principals, or through a link.
That sounds simple, but it changes the value proposition. A conversational system is useful when it answers a question. It becomes more useful when the answer can become an artefact that survives the moment. A team rarely stops at the raw response. They want a one-pager, a summary, or a risk note that they can edit and circulate. Documents give Genie One a native handoff from chat to deliverable, which removes the usual copy-paste tax between a chat interface and a separate editor.
What the stack adds up to
Taken together, these pieces describe a more complete operating model for Genie, and each role gets something concrete.
Application builders get the Conversation APIs: stateful querying, polling, result retrieval, trusted asset signals, reasoning traces, and optional visualization output.
Platform teams get the Management APIs: serialized agents that can be validated, versioned, promoted across workspaces, and backed up.
End users get documents in Genie One: a direct path from conversation to shareable artefact.
None of it is oversold in practice. Prerequisites, validation rules, permissions, capacity, and curation are all spelt out. That restraint is exactly why the combined picture is credible. Genie can now be embedded and managed with clear boundaries and explicit workflows.
The pattern from question, to answer, to artefact, to shared context is how enterprise teams actually work, and the CI/CD for Genie Agents now covers every step of it.
Thoughts?
Is anyone already promoting Genie Agents across workspaces using the serialised representation? What does your pipeline validate before an update goes out?
How are teams handling the polling pattern in production apps? Fixed interval, exponential backoff, or an event-driven wrapper?
Has anyone built the incremental progress pattern by inspecting attachments during
PENDING_WAREHOUSEandEXECUTING_QUERY? Was the UX gain worth the extra client logic?Where do documents fit into your API-driven flows? Do users move to Genie One to draft after the app surfaces the insight, or does drafting remain entirely in the UI?