Custom HTTP routes

Windmill supports custom HTTP routes to trigger runnables or serve static assets and websites. They can only be created by admins workspace. All properties of the route apart from the http path can be modified by any user with write access to the route.

How to use

Create a new route on the HTTP routes page. Specify the path of the http route. You can use the :param syntax to define parameters. Parameters can be handled using a preprocessor. You also need to select the method of the route (GET, POST, PUT, PATCH or DELETE).

The full http route takes the following form:

• Self-hosted Windmill: {base_url}/api/r/{path}
• Windmill cloud: https://app.windmill.dev/api/r/{workspace_id}/{path}

Triggering a runnable

Select the runnable that should be triggered by this route. To quickly get started, you can use the create from template button to generate a runnable template.

Here's an example script:

export async function main(/* args from the request body */) {
  // your code here
}

And if you use a preprocessor, the script could look like this:

export async function preprocessor(
  /* args from the request body, let's assume `name` and `age` */
  name: string,
  age: number,
  wm_trigger: {
    kind: "http",
    http: {
      route: string; // The route path, e.g. "/users/:id"
      path: string; // The actual path called, e.g. "/users/123"
      method: string;
      params: Record<string, string>; // The route parameters, e.g. { id: "123" }
      query: Record<string, string>; // The query parameters
      headers: Record<string, string>;
    }
  },
) {

  // define args for the main function
  // let's assume the id is passed in the path (e.g. "/users/:id") and we want to pass it with the body (name, age) to the main function
  return {
    user_id: wm_trigger.http.params.id,
    name,
    age,
  };
}

export async function main(user_id: string, name: string, age: number) {
  // handle arguments, e.g. update the name and age of the user with the given id
}

The route also supports additional configuration options:

• Request type: Whether the route should return the id (async) or the result (sync) of the runnable.
• Authentication: Whether the route should require authentication. If authentication is required, the user needs to have read access to both the route and the runnable.

Serving static assets and websites

For static assets, upload or specify a file using the S3 picker. The file will be served at the chosen path.

For websites, upload or specify a folder on S3. All its files will be served under the chosen path. Use the full path as the base URL of your website to ensure relative imports work correctly. If no file is found at the requested subpath, Windmill will fallback to index.html.