> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade 2.0 apps to 3.0

> Upgrade legacy Clark apps from YAML APIs to TypeScript APIs (Superblocks 3.0)

<Note>
  In this guide, **2.0** means the earlier Clark app format (YAML APIs, flat project layout). **3.0** means the current format (TypeScript APIs under a `client/` and `server/` layout). Apps built with Clark before April 2026 are often still on 2.0.
</Note>

Upgrading to 3.0 makes Clark faster and more accurate and unlocks the latest editor and Git features. Clark runs the upgrade for you, rewriting and testing your APIs. The change is one-way once you finalize.

## How do I know if my app is on 2.0?

Open the app in the editor. If it is still on 2.0, you will see a banner that lets you **Upgrade**. If you can open the **Code** tab (`< >`) and view the app source, the app is already on 3.0 and will not show the upgrade banner.

## Why upgrade?

| Benefit                         | What you get                                                 |
| ------------------------------- | ------------------------------------------------------------ |
| **Faster, more accurate Clark** | Quicker, more reliable builds and edits, especially for APIs |
| **Revamped editor**             | Inspect code and watch each API run as it is triggered       |
| **Sync to source control**      | Connect the app to your Git repository of choice             |

For how TypeScript APIs work after upgrade, see [Backend APIs](/building-with-clark/backend-apis).

## Features that need alternatives in 3.0

Some 2.0 patterns are not supported the same way in 3.0 apps:

* **Custom backend libraries** used inside APIs
* **Environment variables** in APIs (removed for credential security; use integrations and secrets instead)
* **One-off REST requests** (ad hoc REST steps outside a configured REST integration)
* **Python** API steps

Clark will help you find alternatives during the upgrade. If you need additional support, [contact us](/enterprise/support/help).

## How to upgrade

<Steps>
  <Step title="Start the upgrade">
    Open your application in the Superblocks editor, then click the **Upgrade** button in the banner at the top of the page.

    <img src="https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/upgrade_banner.png?fit=max&auto=format&n=7CbbcscP4WvIOOp8&q=85&s=a041a6829c2b683f99a316ef215622f3" alt="Application banner with button to upgrade" width="1728" height="218" data-path="images/building-with-clark/upgrade_banner.png" />
  </Step>

  <Step title="Confirm and begin migration">
    Confirm the migration details and settings, including adjustment of API write permissions to prevent Clark from testing APIs that write to sensitive integrations. Click **Upgrade now** to start the migration.

    <img src="https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/upgrade_confirmation.png?fit=max&auto=format&n=7CbbcscP4WvIOOp8&q=85&s=303a04361298e604dd828e0c7273c7bf" alt="Application modal with with upgrade details for user to confirm" style={{ width: "60%", display: "block", margin: "0 auto" }} width="1568" height="1588" data-path="images/building-with-clark/upgrade_confirmation.png" />
  </Step>

  <Step title="Let Clark migrate and test">
    Clark will create a checklist and get to work migrating and testing your application. At any point in time you can select **Abort migration** to restore the previous version.

    <img src="https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/migrating.png?fit=max&auto=format&n=7CbbcscP4WvIOOp8&q=85&s=0e8dd87bb53b7d2fa8fbd659bd4d049e" alt="Application in the process of migration" width="3516" height="1664" data-path="images/building-with-clark/migrating.png" />
  </Step>

  <Step title="Finish and finalize">
    <Warning>
      Finalizing permanently deletes the pre-upgrade backup. You cannot abort or roll back to the 2.0 app after that. Clark also loses access to the legacy API code as a reference for future edits.
    </Warning>

    Once the upgrade completes and you are satisfied with the results, click **Finish upgrade** then **Finalize upgrade** to confirm.

    <img src="https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/finish_migration.png?fit=max&auto=format&n=7CbbcscP4WvIOOp8&q=85&s=130a5d503cc902f04356e0f5acbfc3ad" alt="Button to finish upgrade" style={{ width: "70%" }} width="1128" height="522" data-path="images/building-with-clark/finish_migration.png" />
  </Step>
</Steps>

## Abort and restore

To cancel the upgrade at any point, click **Abort upgrade**, then confirm with **Abort and restore**. Aborting does the following:

* Upgrade progress is discarded
* Clark generation stops
* The app restores to the pre-upgrade backup checkpoint
* Clark chat context is cleared
* The page reloads when restore finishes

## Troubleshooting

### APIs could not be upgraded or verified

* Use **Fix with Clark** for APIs that failed conversion
* Use **Get testing instructions** when Clark could not auto-test some APIs (for example write APIs you blocked from testing)
* Manually verify those APIs before you finalize

### Unsupported integrations

The upgrade details modal may also list specific integrations that are not fully supported in 3.0 for your app. Clark still attempts the upgrade, but those APIs may need manual attention. See [Features that need alternatives in 3.0](#features-that-need-alternatives-in-30).

## Related

* [Backend APIs](/building-with-clark/backend-apis)
* [Developing apps in code](/building-with-clark/developing-apps-in-code)
* [Connect to Git](/development-lifecycle/version-control/connect-to-git)