How to export APIs from Amazon API Gateway

How to export APIs from Amazon API Gateway without losing the parts that matter

A renewal, a pricing change or a data residency requirement is forcing you to plan an exit from Amazon API Gateway, and the first practical step is an inventory. API Gateway can export each API's definition per stage as OpenAPI 3.0 or 2.0, with either API Gateway extensions or Postman extensions added to the file. The export does not carry everything that makes the API work in production. Usage plans, API keys, authorizer code and the deployed configuration of stages stay behind, so an exported file describes the routes and their request and response shapes but not how access is granted, metered or authenticated. Treat the export as the starting point for the migration plan, not the migration itself.

The application/json limit on exports affects how you retrieve definitions, so build the pull into a script rather than relying on a one-off console download. Request each stage explicitly, store the output in version control, and record the export date and stage name with each file. The export formats and any size or content limits differ by API type (REST, HTTP or WebSocket), so confirm the current limits and supported formats for the type you run in the AWS documentation for API Gateway before you write the script. Do not assume a limit you read about in an older article still applies.

Once the files are in hand, compare them with what is live. Walk through each API and record the items the export omits: usage plans and their quotas, API keys, authorizer functions and their settings, custom domain names, stage variables, throttling settings, resource policies and any VPC links. Assign each item an owner and a target in the new gateway. Then import one exported definition into a scratch environment and confirm that routes, methods and models match the source. Ask your AWS account team or review the documentation for anything the export does not describe, because the gaps you find at this stage determine how much work the cutover needs.

What API Gateway exports and in which format

This table lists what Amazon API Gateway can export for a REST API, the format of each export, and the limits that matter for a move to a self-hosted gateway. Read each row as a question to answer in your own account before you plan the cutover, because exports cover definitions only and not the runtime controls around them.

Data type	Export method	Format	Limits and what to confirm
REST API definitions	Export per stage from the API Gateway console or CLI	OpenAPI 3.0 or OpenAPI 2.0 (Swagger)	Covers the API's resources, methods and models. Confirm the exact export options in AWS documentation.
API Gateway extensions	Included when the export option for API Gateway extensions is selected	OpenAPI with x-amazon-apigateway extensions	Extensions carry integration and authorizer references that a gateway will not read directly. Map them by hand.
Postman extensions	Included when the export option for Postman extensions is selected	OpenAPI with Postman-specific extensions	Useful for documentation and client tooling. Gateway runtime behavior is not defined by these extensions.
Media type limit	Export request for the application/json media type	JSON output only	Confirm the supported media types and how other content types are represented in the current AWS documentation.
Stage scope	Each stage is exported separately	One file per stage	Repeat the export for every stage, including development and test, and keep the files under version control.
API metadata	Included in the exported document	Title and version fields in the OpenAPI info block	Use these as the starting point for catalog entries. Check the version field is set before exporting.
HTTP and WebSocket APIs	Confirm with AWS documentation	May differ from REST export	HTTP and WebSocket APIs may export differently or with different extensions. Do not assume the REST rows apply to them.

What stays behind in AWS and how to rebuild each part

The OpenAPI export describes the API surface, not the operating controls around it. Usage plans, keys, authorizers, domains, network links and stage settings sit in AWS configuration and must be recorded and recreated separately before any traffic moves.

Usage plans and quotas

Usage plans hold throttling limits and quota periods tied to API stages and keys. None of this appears in the exported definition, so a gateway migration can silently drop rate limits. Record each plan's rate, burst and quota settings and which stages and methods it covers, using the console or the AWS CLI, and add them to the inventory. Recreate the limits in the target gateway with its general rate limiting and quota controls, then confirm that the numbers match before cutover. Check whether any client depends on quota reset dates.

API keys and their values

API keys are issued per client and linked to usage plans. The export carries the requirement that a key is needed but not the key values themselves, so consumers would lose access on cutover. Export key names, enabled state and plan associations into the inventory. Obtain the key values only through a controlled process, and treat them as credentials: store them in a secrets manager and rotate any value that has been shared or exposed. Confirm with the API owners whether clients should keep their existing keys or receive new ones.

Lambda and Cognito authorizer code

Custom authorizers are either Lambda functions or Cognito user pool configurations. The OpenAPI file references them only by name or extension, so the logic that decides who gets access does not move with the definition. Export the Lambda source from your own repository or deployment pipeline, and record the token source, caching settings and identity pool details. Recreate the same checks with the target gateway's authentication plugins or an external identity provider, then test denied and allowed requests for each route.

Custom domains and certificates

Custom domain names map hostnames to API stages and hold TLS certificates, often issued through AWS Certificate Manager. Neither the domain mapping nor the private key moves in an export, and DNS records still point at AWS. Record every hostname, base path mapping, minimum TLS version and certificate source in the inventory. Issue or import certificates in the target environment under your own key management controls, and lower DNS TTLs before cutover so a rollback is quick.

VPC links and integration credentials

VPC links let API Gateway reach private load balancers or services, and integrations may use IAM roles or other credentials. The export shows integration URIs but not the network path or the roles behind them. Document each VPC link's target, subnets, security groups and the IAM role each integration assumes. Rebuild equivalent network routes in the target environment, and replace any role-based access with credentials held in a secrets manager that your security team can audit and rotate.

Stage variables and their values

Stage variables hold per-environment values such as backend hostnames or feature settings, referenced inside integrations. An export records the variable references but not the values set on each stage, so a copy may point at the wrong backend. Capture the value of every variable for every stage from the console or CLI into the inventory. Move sensitive values to a secrets manager, and map non-sensitive ones to the target gateway's configuration files for each environment, then compare the rendered results against the original stage settings.

The sequence for a complete export and how to verify each step

This sequence turns an API Gateway estate into a versioned, reviewed inventory of definitions and the settings that stay behind, so each API can be rebuilt on a self-hosted gateway with nothing lost in the handover.

Freeze the inventory of APIs, stages and domains
The platform or API team lists every REST, HTTP and WebSocket API in each AWS account and Region, along with each stage and every custom domain name mapped to it. Export the list from the console or the AWS CLI into a spreadsheet or CSV file and record the account ID and Region beside each row. The step is complete when the list matches what the account reports on a second run, and nothing created after the snapshot is left out. Confirm the Region list with your cloud team, since APIs in other Regions are easy to miss.
Export each stage definition as OpenAPI
For every API and stage, the API owner or platform engineer exports the definition in OpenAPI format, choosing the version your target gateway tooling expects, and selects whether to include API Gateway or Postman extensions. Save each file under its API name and stage name in a Git repository with a commit message that records the source account, Region and export date. The check is that every file parses as valid OpenAPI and that each stage has its own file, since exports are per stage. Confirm the export format and extension options against the current API Gateway documentation before you start.
Record what the export leaves behind
Usage plans, API keys, authorizers, VPC links and stage variables are not carried in the OpenAPI file, so the team captures them separately. For usage plans, keys and authorizers, record names, IDs, types, associated stages and key metadata only, and keep key values out of the repository. For VPC links and stage variables, record the target endpoints and variable names. The step is complete when each item on the list has a row in an inventory sheet and a named owner, and a reviewer can trace every stage to its non-exported settings. Authorizer code, Lambda functions and secret values are stored in their own systems and must be listed as dependencies.
Capture deployment history and invoke URLs
The team records the deployment history for each stage, including deployment IDs, timestamps and the deployment that is live, along with the current invoke URL and any custom domain mapping. This shows which definition is serving production traffic, which matters if a stage was changed after the export. Store the output alongside the OpenAPI files. The check is that the deployment ID recorded for each stage matches the one that produced the exported file, so you know the export reflects live behavior and not a draft.
Verify each export against the live stage
An engineer re-imports each OpenAPI file into a scratch API or diffs it against the live stage configuration, comparing paths, methods, request and response models, and integration definitions. Differences in integration types, timeouts or mapping templates are noted, because these do not always show up in a definition file. Record the result for each API as pass, pass with noted gaps, or fail, and re-export any failing stage. The step is complete when every stage has a recorded comparison, and any gap is traced to a line in the inventory sheet.
Test the export with a sample of calls
For a representative set of endpoints per API, the engineer sends the same requests to the live invoke URL and records the status codes and response shapes. Requests that depend on keys or authorizers are logged with the correct credentials held by the test team, not stored in the repository. The step is complete when the sampled results match the expected behavior documented by the API owner, and any mismatch is added to the gap list. This confirms the export is a working description and not only a valid file.
Sign off the inventory with API owners
Each API owner reviews the repository folder, the inventory sheet, the verification results and the gap list for their APIs, then signs off in writing, through a ticket or a dated approval record. Owners confirm that consumers, usage plan tiers and key holders are listed correctly and that any unresolved gaps have a planned owner. The inventory is complete when every API has a signed-off record, and the security or compliance lead has a copy for the migration file.

Choosing between the console, CLI and infrastructure code for the export

The API Gateway console lets an administrator open one API, select a stage and download its definition as an OpenAPI file in JSON, with the choice of API Gateway or Postman extensions. This suits a small number of APIs, where a person can check each file by hand and confirm that the right stage was exported.

Who runs it: An account administrator or API owner with console access, usually for a one-off review.
Repeatability: Low. Each download is a manual step, and file names and extension choices depend on the person doing the work.
Scale: Every API and stage needs its own export, so the effort grows with the number of APIs and regions.
What it misses: Usage plans, API keys and authorizer code are not part of the export, so they must be recorded separately from the console pages where they are configured.

Confirm the export options your console version offers in the current API Gateway developer guide before you assign this task to someone.

Building an inventory that a target gateway team can use

The inventory is the working document that turns an export into a rebuild plan, so build it before anyone writes a gateway route. Use one row per API and stage, because the same API often has different throttling, integration targets and authorizers in dev, test and prod. Each row should record the owning team and an escalation contact, the consumers that call it, the authentication type (IAM, Lambda authorizer, Cognito user pool or none), the throttling and quota settings from the stage and usage plan, the integration type (Lambda, HTTP or VPC link), and the path to the exported OpenAPI file for that stage. Confirm the export format and the stage-level extensions against the current API Gateway export documentation before you rely on the file path column, because the export captures the API definition and not everything attached to it.

Consumer discovery is usually the largest manual effort, because API Gateway does not keep a list of who calls an API. Start with usage plan associations, which show which API keys are bound to which stages and rate limits, but remember that keys are not the same as callers and that APIs without usage plans will not appear there. Then check access logs for the stage, if access logging is enabled, and group caller identities, source addresses and user agents by route. Where logging was never switched on, the honest answer is that consumers are unknown, and the inventory should say so and name the owners who can confirm them. Put a date on each consumer entry and mark it as confirmed by a team or inferred from logs, so the gateway team knows which routes can be cut over with a notice and which need a longer parallel run.

What to plan before the AWS contract or usage ends

Exports are only one piece of leaving API Gateway. The cards below cover the timing, traffic shifting, account access and record keeping that decide whether the export work holds up under a contract end date. Check your own AWS agreement for notice periods and data retention terms, since these vary by contract.

Set the export and inventory deadline

Fix the date by which every REST, HTTP and WebSocket API has been exported and listed in one inventory. The inventory should record each API, its stages, custom domains, integrations and whether it uses usage plans, API keys or authorizers. Work backward from your contract or usage end date to set this date, and confirm with your account team which dates apply to your account.

Plan the stage-by-stage cutover

Shift traffic one stage at a time, starting with the lowest-risk stage such as development, then staging, then production. For each API, decide how DNS, custom domains and client certificates move, and keep a documented rollback path that points traffic back to API Gateway. Test each cutover against the same request set before moving the next stage.

Keep the AWS account readable

During parallel running, keep the AWS account, IAM roles and CloudWatch access in place so the team can still read configurations, metrics and logs. Avoid deleting APIs, stages or related Lambda functions until the cutover is signed off. Tag resources that are scheduled for removal so nobody decommissions a dependency by mistake.

Retain definitions and logs for audit

Store the exported OpenAPI files, the inventory, authorizer code, usage plan settings and the access logs in a location you control, with versioning and restricted access. Auditors and incident responders often ask for the configuration that was active on a past date, so record export timestamps and the stage each file came from. Confirm the retention period your compliance program requires before deleting anything in AWS.

Review the AWS agreement terms

Ask your AWS account team to confirm any enterprise agreement, support plan or committed-spend terms that affect the end date, including notice periods and any penalty for reducing usage. Ask how long AWS retains account data after service ends and where that is documented for your contract. Record the answers in the migration plan so finance and engineering use the same dates.

Assign owners for each API

Name one owner per API who signs off the inventory entry, the test results and the cutover for each stage. Owners should also agree who handles consumer communication, since clients that call the invoke URL directly will need a new endpoint and possibly new keys. Without named owners, APIs with no clear consumer tend to be left behind at the deadline.

Questions teams ask before they export their APIs

How much effort does exporting APIs from Amazon API Gateway take?

The effort depends on how many APIs you run, how many stages each one uses, and how much of their behavior sits outside the exported definition. Producing a definition for each stage is the mechanical part. The slower work is checking what the export does not carry: usage plans, API keys, authorizer code, and settings changed in the console that were never recorded in code. Exports are limited to the application/json format, so confirm how each definition will be delivered before you script the job. Build an inventory first (APIs, stages, authorizer types, usage plans and consumers), because those counts drive the effort more than the export command itself.

Can our own team export the APIs without outside help?

A platform or cloud team with console or CLI access to the relevant AWS accounts can export definitions for a small set of APIs. The harder questions are whether the inventory is complete, which settings did not come across, and who owns each API. Outside help is most useful when you have many APIs across several accounts, settings changed by hand that nobody documented, or no clear owner for each API. Your team will still need to decide the target gateway and test it. Confirm that you have people comfortable with OpenAPI files, AWS permissions and the gateway you plan to adopt.

What does the export work need from our side?

The work needs three things from your side:

Read access to the API Gateway configuration in each AWS account and region in scope. Confirm the exact IAM actions with AWS documentation and your security team before granting them.
API owners who review each exported definition and sign off on it, including the integrations and authorizers they depend on.
A secure, versioned place to store the exports, such as a Git repository or a storage bucket inside your own accounts, with access limited to the people who need it.

Agree on who approves changes to those files before the work begins, so the inventory reflects what is actually live.

How long does the export take, and what sets the timing?

The timing depends on the number of APIs and stages, the number of authorizers and consumers that need review, and how quickly API owners can respond. Change freeze windows, the number of integrations that need testing, and whether traffic will move stage by stage also add time. Exporting itself is usually quick once the inventory is clear, so the schedule is driven by review and testing. Ask any partner for milestones tied to the inventory, review, rebuild, testing and cutover, rather than one overall date that hides where the time goes. Confirm which dependencies on your side could delay each milestone.

Is exporting the API definitions enough to switch gateways?

No. The export captures API definitions and their integrations per stage, but it does not rebuild the runtime behavior around them. Usage plans, API keys and their quota settings stay behind and must be recreated on the new gateway. Authorizer code, including any Lambda authorizers, needs replacing with an equivalent authentication method. Custom domains, certificates and other edge settings also need recreating. Traffic must then move in stages with testing at each step. Treat the exported files as the starting inventory for the migration, not as the migration itself.

What should we ask a partner to include in a written scope?

A written scope should make the boundaries of the work explicit. Ask for:

The list of AWS accounts, regions, APIs and stages in scope, and what is excluded.
The inventory method and the format of the export files, with a statement of where they will be stored.
A list of settings the export does not carry, such as usage plans, keys and authorizers, and how each will be handled.
The review and sign-off steps for API owners, and the testing approach before any cutover.
Deliverables, milestones, handover documentation and the support available after handover.

DeployOpen agrees scope, deliverables and timelines in writing before work starts and gives no published price list, so a quote follows from the written scope.

How DeployOpen scopes and delivers an API Gateway export

DeployOpen approaches the export of Amazon API Gateway definitions as a scoped engagement inside your own AWS accounts or data centers. We agree in writing which stages, APIs and integrations are in scope, then document what exports cleanly and what must be rebuilt by hand.

How we scope

Inventory every REST, HTTP and WebSocket API across accounts, regions and stages before any export begins
Record which integrations, authorizers, usage plans and API keys each API depends on, since these do not travel in exports
Agree the scope, deliverables and timeline in writing; engagements are fixed-scope and quoted from that written scope

How we build

Export OpenAPI definitions per stage, check them against the application/json limit, and mark any gaps for manual rebuild
Recreate authorizers, rate limits and key-based access with self-hosted gateway policies, tested against the original behavior
Keep the exported definitions, conversion scripts and configuration in version control so every change is reviewable

How we hand over

Deliver a written inventory listing each API, stage, export file and known gap, with an owner for each item
Document the rebuilt routes, plugins and credentials, plus a runbook for parallel running and stage-by-stage cutover
Walk your platform and security teams through the handover so they can operate the gateway and its configuration

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover
Confirm with your own environment and the gateway vendor which versions and support windows apply before scoping
Scope any later changes in writing, so cutover checks and documentation stay current with each new stage

How to export APIs from Amazon API Gateway