Migration Guides

Getting Started with API Migration - Agent

Migrate an existing API tutorialLocal with an AI agent

Import an API into Zuplo and verify that a request through the gateway matches the original backend.

Follow along using

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 24 or later and Git.
A Zuplo account 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

Create the migration project

Run:
```
Code
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.

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 from this directory before starting your agent.
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.

If you don't have an OpenAPI document, download the
Swagger Petstore OpenAPI document
.

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.

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:

Code
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.

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.
Deploy and move traffic gradually

Follow Deploy to the edge. 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.

Next steps

Editor tutorial for the exact route configuration and update workflow.
Migration overview for translating another gateway's configuration.
API key authentication to protect routes with managed keys.

Editor Migration Overview

Migrate your API with an agent

Create the migration project

Run:
```
Code
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.

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 from this directory before starting your agent.
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.

If you don't have an OpenAPI document, download the
Swagger Petstore OpenAPI document
.

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.

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:

Code
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.

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.
Deploy and move traffic gradually

Follow Deploy to the edge. 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.