retool.com

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

Yes. Retool's app builder accepts apps built on Lovable, Replit, and other platforms, as well as React code you've written yourself. You import by uploading a ZIP file or syncing with GitHub, and the imported app then runs inside your Retool environment with its authentication, access controls, and audit logging applied. This fits teams that already have a working prototype and want to keep it rather than rebuild from scratch.

What the import path actually covers

Retool describes the import flow as a way to "deploy apps built in Lovable, Replit, and other platforms" by uploading a ZIP or syncing with GitHub. The same page frames this under a "Secure your vibe-coded apps" heading, which tells you the intended audience: apps generated quickly by AI tools or low-code builders that now need production-grade handling.

Two things follow from that framing:

• The import is a deployment step, not a rewrite. You bring the built artifact in; you don't re-describe the app to Retool's AI builder.
• Governance is applied at the environment level. Because the app lands in your Retool workspace, the security posture described for Retool apps — auth, access controls, audit logging — is what the imported app inherits.

Importing vs. building with AI vs. importing React

Retool presents three distinct ways to get an app into the platform. They suit different starting points, so pick by what you already have:

If your app already exists and works, import is the shortest route. If you're starting from a spec, the AI app builder generates "a full, production-ready app" from a prompt. The MCP/CLI path is for teams that want to drive app creation from their own tooling and then deploy into the governed environment.

What happens to security after import

This is the part that usually decides the question. Retool states that what you build is "enterprise-grade from the start — no rebuild, no audit scramble, no IT veto," and that deployment comes with auth, access controls, and audit logging already in place.

For an imported app, the practical reading is:

1. Authentication is handled by your Retool environment rather than bolted on afterward.
2. Access control follows your existing permissions — Retool says app data access "is governed by your existing permissions—no extra configuration required."
3. Audit logging is present because the app runs inside Retool, not as a standalone deployment.

The claim worth verifying in your own environment is the permissions inheritance: confirm that the data sources your imported app calls are reachable under the same permission model your team already uses.

Connecting imported apps to production data

An imported front end is only useful if it can reach real data. Retool says every app connects directly to production data sources, and points to a full integrations list covering databases, APIs, and LLMs. The site does not enumerate every connector on the page referenced here, so check the integrations list for your specific database or API before committing.

A sensible sequence for a first import:

1. Confirm your target data source appears in Retool's integrations list.
2. Import the app via ZIP or GitHub sync.
3. Point the app at the data source and verify queries return under your existing permissions.
4. Check that auth and audit logging behave as expected in a non-production workspace before promoting.

When import is the right call — and when it isn't

Import makes sense if you have a working app from Lovable, Replit, or a React codebase, and the blocker is governance rather than functionality. You keep the UI you built and gain the security and operational layer.

Import may not be the best fit if the app is still a rough prototype whose logic you expect to change substantially — in that case the AI app builder, which generates from a prompt and connects to data directly, may get you to a maintainable app faster than importing and then reworking it.

Either way, the decision hinges on one check you can do early: whether your data sources are supported and whether your existing permissions carry over cleanly. Settle that first, and the rest of the import is a deployment step.

Retool apps can connect directly to your production databases, APIs, and LLMs, and access to those sources is governed by the permissions you already have in place—no extra configuration required, according to Retool. In practice, that means you can point a Retool app at an existing system of record and let your current access rules decide who sees and does what. The site states that a full list of integrations is available on its integrations page, so the exact catalog should be checked there rather than assumed.

How the connection model works

Retool describes a single pattern across source types: every app you build connects directly to your production data sources, and access is governed by your existing permissions. The practical implication is that Retool does not ask you to duplicate your data into a separate store or rebuild your permission model before an app can read from a database or call an API.

For a concrete example: if a support team already has read access to a customer records database, a Retool app built on that database inherits the same governed access rather than opening a new, unmanaged path to the data. The same logic applies to API endpoints and to LLM integrations—the app calls the source, and your existing controls decide what is reachable.

Databases and APIs

The site's core claim is that apps connect to "any database, API, or LLM." Databases and APIs are the two foundational source types: databases supply the records an internal tool displays and edits, and APIs let the app reach systems that expose their functionality over HTTP rather than through direct database access. Because access follows existing permissions, the main prerequisite is that the identity running the app already has a legitimate path to the source.

LLM integrations

Retool lists LLMs alongside databases and APIs as connectable sources, and its app builder is positioned around generating production-ready AI applications. If your goal is an internal tool that calls a model—for summarization, classification, or an agent-style workflow—the model is treated as one more integration rather than a separate product.

Bringing in apps built elsewhere

Retool supports importing React code, including apps built on Lovable, Replit, and other platforms, by uploading a ZIP file or syncing with GitHub. This matters if your data connections already live inside an app built outside Retool: you can move the app into a governed Retool environment instead of rebuilding the integrations from scratch. The expected result is that the imported app runs inside the same permission and governance boundary as anything built natively.

What "governed by existing permissions" means for your decision

The claim to verify before committing is whether your specific source—a particular database engine, an internal API, a model provider—is on the supported integrations list and whether your current permission setup maps cleanly onto it. Two checks make this concrete:

• Confirm the source is listed. Use the integrations page as the authoritative catalog rather than inferring support from the general "any database, API, or LLM" statement.
• Confirm the permission path exists. Since access is governed by existing permissions, an app can only reach what the underlying identity is already allowed to reach. If a source is locked down to a narrow group, expect the app to inherit that narrowness.

Retool also states that apps ship with authentication, access controls, and audit logging already in place, which is relevant if the reason you are evaluating integrations is a security review. The site does not publish per-integration limits or configuration details in the material available here, so treat the integrations page and the linked documentation as the place to confirm specifics.

Where to go next

Start with the integrations list to confirm your database, API, or model is supported, then check that the identity your app will use already has a governed path to that source. If you are migrating an existing React app, the ZIP upload or GitHub sync route is the documented entry point. Pricing and plan-level limits are not covered in the source material; consult the pricing page directly if cost or tier restrictions affect your decision.

Retool's AI app builder turns a written prompt into a full, production-ready internal app, and its AI agents let you build and deploy apps through an MCP server or CLI inside your governed Retool environment. Both paths assume you already have a Retool account and access to your production data sources; the output is meant to pass security review from day one rather than be rebuilt later.

What the AI app builder does

You describe the app you want in plain language, and Retool generates a complete app with enterprise security and governance built in. According to Retool, the result is "production-ready" from the start — authentication, access controls, and audit logging are already in place, so there is no separate hardening pass before shipping.

The builder is positioned for both technical and business teams: business users can move fast while IT keeps visibility and centralized governance.

Including data in a prompt with @

Inside the prompt, you use @ to reference and include data. This is how the generated app is wired to real sources rather than placeholder content. Because every Retool app connects directly to production data sources and access is governed by your existing permissions, the data you pull in through @ inherits those same permission rules — Retool states no extra configuration is required.

A practical example: if you need an operations dashboard for warehouse staff, you would prompt for the layout and use @ to attach the relevant production tables or APIs, and the app would respect each viewer's existing access level.

Building with AI agents via MCP server or CLI

Beyond the prompt-based builder, Retool supports agent-driven development:

• MCP server or CLI — you use either to build an app and then deploy it into your governed Retool environment.
• React code import — apps built on platforms like Lovable or Replit can be deployed by uploading a ZIP file or syncing with GitHub.

The key distinction is where the app lands: agent-built and imported apps are deployed within Retool's governed environment, so they inherit the same auth, access controls, and audit logging as apps built in the builder.

What "governed environment" means in practice

Retool frames governance as the reason AI-generated apps are usable at all. The platform's stated model:

Retool says more than 10,000 teams use it to generate production-ready AI applications, and cites customers such as Ramp (reported $8M and 20,000+ hours saved) and DoorDash (reported $6M and 36,000+ hours saved) — figures that come from Retool's own case stories and should be read as vendor-reported.

How to choose between the two paths

• Use the AI app builder when you can describe the app and its data needs in a prompt and want a finished app quickly, including for non-developers.
• Use MCP/CLI agents when you want to generate or iterate on an app programmatically and deploy it into the governed environment.
• Use code import when the app already exists on another platform (Lovable, Replit, or a GitHub repo) and you want to bring it under Retool's security and governance.

All three end in the same governed deployment, so the choice is about how you like to build, not about differing security outcomes.

Getting started and what to check

Retool offers a free way to explore the new app builder — the site's call to action is to "explore the new Retool app builder for free." Pricing details for paid plans are listed on Retool's pricing page; check that page directly for current tiers, since plan limits and feature gating are not specified in the material summarized here.

Before you build, confirm two things: that the data sources you plan to reference with @ are already connected in your Retool instance, and that your existing permission model covers the users who will open the app. Both determine whether the generated app is immediately usable or needs adjustment.

Retool builds authentication, access controls, and audit logging into every app you deploy, and it governs data access through the permissions your organization already has in its underlying systems. That means an app built in Retool is meant to be production-ready from the start—no separate security rebuild or audit scramble before it can pass review. The details below reflect what Retool states on its site; for the specific controls available on your plan, confirm against Retool's current documentation and pricing page.

Security built into deployment

Retool's core claim is that governance ships with the app rather than being bolted on afterward. When you deploy, the platform states that auth, access controls, and audit logging are already in place. In practice this covers three layers:

• Authentication — who can sign in to an app.
• Access controls — what each signed-in user can see and do inside it.
• Audit logging — a record of activity for review.

Because these are described as built in, the intended workflow is that a team can move quickly on building while still producing something that passes a security review. Retool frames this as avoiding the trade-off between speed and shipping something that will "actually pass a security review."

Data access follows your existing permissions

Every Retool app connects directly to production data sources, and Retool states that access is governed by your existing permissions—no extra configuration required. This is the key mechanism to understand: Retool does not create a parallel permission model for your data. If a user lacks access to a table or system at the source, that restriction carries through to the app.

A practical example: if a support agent's database role only permits reading customer records for their region, an app querying that database runs under those same constraints. You are not re-implementing row-level rules inside Retool; you inherit them.

The trade-off to plan for: because access mirrors the source system, the quality of your app's security depends on how well those source permissions are maintained. Teams with messy or overly broad database roles should clean those up first, since Retool will faithfully reflect them.

Centralized governance for IT visibility

Retool positions governance as centralized: business teams can build and move fast, while IT retains full visibility and control. The site describes this as the foundation that makes app generation work at scale—more teams building without adding new risk.

This matters most when multiple teams build apps independently. Rather than each team inventing its own access rules, governance sits in one place that IT can monitor. If your organization has a central platform or IT function that needs oversight of internal tools, this is the model to evaluate against your own requirements.

AI-generated and imported apps inherit the same controls

Retool's newer app builder lets you describe an app in a prompt and get a full app back, and the company states that enterprise security and governance are built in. The same applies to apps brought in from elsewhere:

• AI agents — you can use Retool's MCP server or CLI to build an app and deploy it into your governed Retool environment.
• Imported React code — apps built in Lovable, Replit, and similar platforms can be deployed by uploading a ZIP file or syncing with GitHub.

The point for a security reviewer: an app generated by AI or imported from a third-party builder still lands inside the same governed environment, rather than bypassing it. If your concern is shadow IT from fast AI prototyping, this is the relevant control.

What to verify before deciding

Retool's site makes broad governance claims but does not enumerate every control, certification, or plan-level restriction. Before committing, check:

1. Which controls are on your plan — auth options, granular access controls, and audit log retention may vary by tier. Review the pricing page and current docs.
2. How your source permissions map — audit the database and API roles your apps will use, since Retool inherits them.
3. Your compliance requirements — match Retool's stated governance features against the specific standards your organization must meet, and confirm details with Retool directly.

Retool reports that 10,000+ teams use it to generate production-ready AI applications, and cites customers such as Ramp and DoorDash on time and cost savings. Those figures speak to adoption and efficiency, not to your specific compliance posture—treat them as context, not as a security guarantee.