How to create an HTTP endpoint in Wix Studio Two

4 days ago

4 min read

Updated: 2 days ago

In Studio Two, you create an HTTP endpoint from the Code tab by choosing Backend, then HTTP Endpoint in Wix Extension Builder. Wix generates a TypeScript file in src/api/, and its path becomes the route. You then edit the handlers, call the route from frontend code with httpClient.fetchWithAuth(), and publish.

Status: Endpoints serve your site's own frontend code only. Calls from outside systems are not supported yet.

Before you start

A Studio Two site project with access to the Code tab.
A dashboard page extension if you want a quick place to test the endpoint.
Frontend code that can import from @wix/essentials, such as an ERC, a Data Source or a dashboard page.
For the review example: a CMS collection with the ID Reviews, read set to ANYONE and insert, update and remove set to ADMIN.

Step by step

Generate the endpoint file. In the Studio Two editor, open the Code tab and then Wix Extension Builder in the VS Code sidebar. Under Create an Extension, pick Backend, then HTTP Endpoint. Enter a Name in lowercase letters, numbers and hyphens, use slashes to nest segments (for example stock/levels), and click Generate.
Understand the route. The new file sits at src/api/<name>.ts and Wix serves it at the route <name>, with no /api prefix. Every .ts or .js file in src/api/ except .d.ts files becomes a route, so keep shared helpers elsewhere. To rename or move a route, rename or move the file.
Edit the handlers. The generated file exports a GET handler that returns a JSON message and a POST handler that echoes the JSON body it receives. Each handler is an exported constant named after the HTTP method, typed as APIRoute from @wix/custom-extensions/types. It receives a context with request, url and params, and returns a standard Response.
Validate input and report errors. Return Response.json() for JSON and set the status yourself for expected failures, such as 400 for invalid input. Wrap request.json() in a try block so a malformed body returns 400. An uncaught error gives the caller a 500 with the body Internal Server Error.
Check who is calling. Endpoints have no built-in permissions, so any visitor can call them. In the handler, call auth.getTokenInfo() from @wix/essentials and check subjectType (VISITOR, MEMBER or USER). Allow only the identity you expect, and take the caller's ID from subjectId, not from the request body or URL.
Elevate only the calls that need it. Wix API calls in a handler run as the caller. To run one call with elevated permissions, wrap that method with auth.elevate() and call the wrapped version. Do the caller check and input validation first, because an elevated call ignores the permissions of the caller and the collection.
Store third-party keys in the Secrets Manager. If the endpoint calls a third-party API, keep the key in the Secrets Manager. Read it in the handler with Get Secret Value from @wix/secrets, wrapped in auth.elevate(). The code runs on Wix servers, so the key does not reach the browser.
Call the endpoint from frontend code. Use httpClient.fetchWithAuth() from @wix/essentials, which attaches the access token. Build the URL from the origin of import.meta.url, then import.meta.env.WIX_SERVER_BASE_PATH (use / if unset), then the route without a leading slash. Check response.ok or response.status yourself, because fetchWithAuth() does not throw on 4xx or 5xx.
Test from a dashboard page. Add a dashboard page if you have none, call the endpoint in its component and show the returned message, for example in the EmptyState subtitle. Open the page under Custom Pages in the site dashboard. Dashboard calls work as soon as you save, but they run as a Wix user, not as a site member.
Publish the site. Click Publish in the Studio Two editor to ship the endpoint with your site. After publishing, test as a real caller on the live site, for example a logged-in member, and check the result, such as a new item in the collection.

Good to know

An HTTP endpoint has no configuration file. It is not registered in extensions.ts and does not appear under My Extensions. To remove it, delete the file.
Use a relative URL such as '/reviews' and you get a 404 on a site page, because it resolves against your site's domain. Endpoints are served from a different domain.
A request without an access token fails with a 401 before the handler runs.
In the Studio Two editor and Preview, calls from site code fail with a 403 until your latest code changes are published.
Endpoints share the backend compute limits of all Studio Two backend code. Use a Backend Events extension for reacting to site events and a service plugin to change how a business solution works.

parnii note

Treat every endpoint as public: check the caller and validate input before any elevated call. Publish before you test from the editor or Preview, since those calls fail with a 403 until the code is deployed.

FAQ

Where do HTTP endpoint files live in Studio Two?

They live in src/api/. The file path sets the route, so src/api/stock/levels.ts serves the route stock/levels. There is no /api prefix in the route.

Why does my endpoint call return 401 or 404?

A 401 means the request carried no access token, so use httpClient.fetchWithAuth(). A 404 on a site page usually means the URL was relative, such as '/reviews', instead of built from import.meta.url.

Can external systems call a Studio Two HTTP endpoint?

No, not yet. Endpoints serve your site's own frontend code, such as ERCs, Data Sources and dashboard pages. Calls from outside systems are not supported.