Introduction

With API Gateway and Serverless Framework, the default endpoint usually includes the stage name in the path, such as /prod/users. In practice, you do not remove stages from AWS itself. You keep the stage for deployment purposes and hide it behind a custom domain and base-path mapping so the public URL becomes cleaner.

Why the Stage Appears in the First Place

A default API Gateway URL often looks like this:

https://abc123.execute-api.us-east-1.amazonaws.com/prod/users

The prod segment is the API Gateway stage. Serverless Framework creates and deploys that stage; it does not abolish the underlying AWS routing model. So there are really two different goals:

• keep using stages for deployment separation
• stop exposing the stage name in the public URL

The normal production answer is yes to the first goal and yes to the second.

Use a Custom Domain for the Public URL

The usual fix is to map a custom domain such as api.example.com to the stage. Then callers see a clean URL:

https://api.example.com/users

The stage still exists behind the scenes, but clients no longer have to include it in the path.

A common serverless.yml setup looks like this:

1service: users-api
2
3provider:
4  name: aws
5  runtime: nodejs20.x
6  stage: prod
7  region: us-east-1
8
9functions:
10  getUsers:
11    handler: handler.getUsers
12    events:
13      - http:
14          path: users
15          method: get
16
17plugins:
18  - serverless-domain-manager
19
20custom:
21  customDomain:
22    domainName: api.example.com
23    stage: prod
24    basePath: ''
25    createRoute53Record: true
26    endpointType: regional
27    securityPolicy: tls_1_2

The key setting is basePath: '', which maps the stage to the root of the custom domain.

The Lambda Code Does Not Need to Change

Removing the stage from the public URL is a routing concern, not a Lambda-handler concern. A function can stay exactly the same.

1module.exports.getUsers = async () => {
2  return {
3    statusCode: 200,
4    headers: {
5      'content-type': 'application/json'
6    },
7    body: JSON.stringify([
8      { id: 1, name: 'Ava' },
9      { id: 2, name: 'Liam' }
10    ])
11  };
12};

The only thing that changes is how API Gateway routes requests to that function.

Separate Environments with Separate Domains

If you have several environments, avoid trying to make one domain ambiguously represent several stages. A cleaner pattern is:

• 'api.example.com for production'
• 'api-staging.example.com for staging'
• 'api-dev.example.com for development'

This keeps environment boundaries obvious and avoids accidental production traffic hitting the wrong stage.

What You Usually Cannot Change

The raw execute-api.amazonaws.com hostname generally follows API Gateway’s own stage-aware structure. If you want a stage-free public URL, use a custom domain. Expecting the default AWS hostname to behave like a polished production URL is usually the wrong mental model.

It is also worth checking whether your service uses REST API or HTTP API configuration, because the exact Serverless Framework settings can differ slightly between them even though the public-domain idea stays the same.

Common Pitfalls

• Expecting the default execute-api hostname to hide the stage without any custom-domain setup.
• Forgetting basePath: '' and leaving an extra public path segment in place.
• Mapping the wrong stage to the production domain.
• Overcomplicating the Lambda function even though the problem is only in API routing.
• Mixing REST API and HTTP API examples without checking which one your service actually uses.

Summary

• The stage name is part of API Gateway’s default deployment URL structure.
• In Serverless Framework, the practical way to hide it is a custom domain with base-path mapping.
• 'basePath: '' maps the stage to the root of the public domain.'
• The Lambda handler code does not need to change for this URL cleanup.
• Separate domains per environment are usually clearer than hiding multiple stages behind one domain.