# Getting Started with API Migration - Agent

<WizardSteps build="migrate" method="agent" />

<MethodTabs build="migrate" method="agent" />

Have a coding agent import an existing API and configure Zuplo to forward its
requests. You'll review the route changes and verify responses before moving any
clients.

## Prerequisites

- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
- A [Zuplo account](https://portal.zuplo.com) and an installed coding agent.
- Your API's OpenAPI document and upstream URL, or the Petstore document linked
  below.

## Migrate your API with an agent

<Stepper>

1. **Create the migration project**

   Run:

   ```bash
   npx create-zuplo-api@latest migrated-api
   cd migrated-api
   ```

   When prompted, choose **Yes** to create a matching Portal project, complete
   sign-in, and select your Zuplo account. Select the coding agent you use when
   asked. The CLI creates and links the hosted project. See
   [`create-zuplo-api`](../../cli/create-zuplo-api.mdx).

   :::tip{title="Zuplo skills"}

   The scaffold installs Zuplo skills in this project for Codex and Cursor and
   configures the Claude Code plugin. If setup fails, follow
   [Agent Skills](../../build-with-ai.mdx#agent-skills) from this directory
   before starting your agent.

   :::

2. **Get your existing OpenAPI document**

   Get your API's OpenAPI document from its repository, API documentation, or
   current gateway and save a copy in the project root. The prompt below uses
   `openapi.json`; substitute your file's name if it differs.

   <p>
     If you don't have an OpenAPI document, download the{" "}
     <a href="/docs/downloads/petstore-openapi.json" download="openapi.json">
       Swagger Petstore OpenAPI document
     </a>
     .
   </p>

   Give the agent your upstream URL and current authentication requirements.
   Choose a read-only operation to verify. For Petstore, use
   `https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available`.

3. **Give the agent a bounded migration task**

   Open the agent in the project directory. Provide the upstream URL and
   operation you chose, then use this prompt:

   ```text
   Read the project instructions and bundled Zuplo docs. Import ./openapi.json
   into ./config/routes.oas.json with:
   npx zuplo openapi merge --source ./openapi.json --destination ./config/routes.oas.json

   For the read-only operation I selected, configure x-zuplo-route with a
   urlForwardHandler from $import(@zuplo/runtime). Set options.baseUrl to my
   original API's base URL. Check imported paths so server URL prefixes are
   not duplicated. Preserve the operationId and unrelated route configuration.

   Start npm run dev. Call the original API and the matching localhost:9000
   route with the same query parameters and required headers. Compare their
   status codes and response structure, allowing for changes in live data.
   Show the diff and report actual test results, including failures.

   Do not delete other routes, change client URLs or DNS, add credentials to
   source files, or deploy. Identify any imported paths, security declarations,
   or server URL prefixes that need manual review. For private APIs, OpenAPI
   security metadata is not a substitute for gateway authentication policies.
   ```

   Ask the agent to preserve your existing authentication, rate limits, and
   transformations explicitly; don't infer them from the OpenAPI file alone.

4. **Review and verify the migration**

   Check that the handler points to the original API, that server-path prefixes
   aren't duplicated, and that unrelated routes remain intact. Review `git diff`
   before accepting the agent's changes.

   With `npm run dev` running, call your chosen operation directly and through
   the local gateway. Use the same headers and query parameters in both
   requests, and compare the status and response structure. For a private API,
   also test invalid or missing credentials and the request bodies and error
   responses that clients depend on.

5. **Deploy and move traffic gradually**

   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx). Repeat
   the tests against the deployed gateway URL, then point one test client at it.
   Keep the original endpoint available while migrating clients in stages so you
   can restore their previous base URL if needed.

</Stepper>

## Next steps

- [Editor tutorial](./local.mdx) for the exact route configuration and update
  workflow.
- [Migration overview](../../articles/migration-overview.md) for translating
  another gateway's configuration.
- [API key authentication](../gateway/add-api-key-auth/local.mdx) to protect
  routes with managed keys.