About HTTP Endpoints

Wix CLI projects support HTTP endpoints, which you use to build backend APIs for handling HTTP requests and coordinating frontend and backend logic. HTTP endpoints can serve any kind of data.

File-based routing

The location of an endpoint file in your project determines its URL. Place a file at src/api/<name>.ts, and it's exposed at /<name>, with no prefix. For example, src/api/users.ts becomes the route /users. A dynamic segment in square brackets becomes a route parameter. For example, src/api/users/[id].ts serves /users/42, and the handler reads 42 as params.id.

You can create an endpoint file yourself, or generate one by running npm run generate and selecting HTTP Endpoint.

HTTP method handlers

Each endpoint file exports one or more HTTP method handlers, such as GET or POST. A handler receives the standard web Request and returns a standard Response, so you can return any content type, including JSON, plain text, images, and RSS feeds.

Type your handlers with the APIRoute type from @wix/custom-extensions/types. A handler receives a context object that includes the following properties:

• request: The incoming Request.
• url: The request URL, as a URL object.
• params: The route parameters from dynamic segments in the file path.

Server-side runtime

Endpoints run on the server, not in the browser. This means you can:

• Read environment variables, including sensitive values such as API keys. Frontend code can't read the environment variables you define.
• Call external services without exposing credentials in your frontend bundle.

Calling endpoints from frontend extensions

Frontend extensions, like dashboard pages and site widgets, call endpoints using httpClient.fetchWithAuth() from @wix/essentials. This attaches the current user's access token to the request as an Authorization header, which the endpoint can then use to make elevated SDK calls for operations the user can't perform directly.

For the full pattern, see Add HTTP Endpoints to Your Project.

Permissions and security

Unlike web methods, HTTP endpoints don't have a built-in permissions model. A request that doesn't include a Wix access token gets a 401 response. Frontend extensions add the current user's token when they call your endpoint with httpClient.fetchWithAuth().

A valid token doesn't tell you whether the caller is allowed to perform an operation. Before you make an elevated call or return sensitive data, check the caller and validate the input:

• In the handler, use Get Token Info from @wix/essentials to read the token's subjectType and allow only the callers you expect. For example, a call from a dashboard page has the subjectType USER.
• Validate the request body and route parameters before you use them.

Use cases

Use HTTP endpoints when you need to:

• Integrate with external APIs or services that require HTTP requests.
• Handle complex form submissions or file uploads.
• Serve dynamic content like images, RSS feeds, or personalized data.
• Build REST APIs with multiple HTTP methods.
• Access runtime data or server-side databases.

See also

• Add HTTP Endpoints to Your Project
• Elevate API Call Permissions
• About Environment Variables
• Migrate from HTTP Functions to HTTP Endpoints
• Migrate from Web Methods to HTTP Endpoints