routes

Creates, updates, deletes, gets or lists a routes resource.

Overview

Name	routes
Type	Resource
Id	vercel.project_routes.routes

Fields

The following fields are returned by SELECT queries:

list

A routing rule with metadata for project-level routing.

Name	Datatype	Description
id	string	Unique identifier for the routing rule.
name	string	Human-readable name for the routing rule.
description	string	Optional description of what the routing rule does.
enabled	boolean	Whether the routing rule is enabled. Defaults to true. (false, true)
raw_dest	string	Original destination provided by user. (wire: rawDest)
raw_src	string	Original source pattern provided by user (path-to-regexp or regex). Used to display the user's input in API responses. (wire: rawSrc)
route	object	The route definition from @vercel/routing-utils.
route_type	string	Computed route type based on the route configuration. Only present in API responses, not stored in S3. (redirect, rewrite, set_status, transform) (wire: routeType)
src_syntax	string	The syntax type of the source pattern. Determines how the pattern is compiled to regex. (equals, path-to-regexp, regex) (wire: srcSyntax)
staged	boolean	Whether this route is new and not yet published to production. Set to true only when a route is first created via add-route. Cleared (set to false) when a version is promoted to production. (false, true)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	project_id	version_id, q, filter, diff, team_id, slug	Get the routing rules for a project. Supports searching by name/ID/pattern, filtering by route type, and diffing staged changes against production.
create	insert	project_id, route	team_id, slug	Add a single routing rule to a project at a specified position. Defaults to the end of the list if no position is provided. The route is enabled by default. Stages a new version with the added route.
update	update	project_id, route_id	team_id, slug	Replace a routing rule identified by its ID, or restore it from the current production version. Stages a new version with the modified route.
stage	replace	project_id	team_id, slug	Stage routing rules for a project. Set overwrite to true to replace all existing rules, or omit it to merge with existing rules by ID. Returns the new staged version.
delete	delete	project_id	team_id, slug	Delete one or more routing rules from a project by ID. Stages a new version with the routes removed.
generate	exec	project_id, prompt	teamId, slug	Generate a routing rule configuration from a natural language description. Returns a suggested route configuration that can be reviewed and saved.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
project_id	string
route_id	string
diff
filter	string
q	string
slug	string	The Team slug to perform the request on behalf of.
teamId	string	The Team identifier to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)
version_id	string	(wire: versionId)

SELECT examples

list

Get the routing rules for a project. Supports searching by name/ID/pattern, filtering by route type, and diffing staged changes against production.

SELECT
id,
name,
description,
enabled,
raw_dest,
raw_src,
route,
route_type,
src_syntax,
staged
FROM vercel.project_routes.routes
WHERE project_id = '{{ project_id }}' -- required
AND version_id = '{{ version_id }}'
AND q = '{{ q }}'
AND filter = '{{ filter }}'
AND diff = '{{ diff }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

INSERT examples

create

Add a single routing rule to a project at a specified position. Defaults to the end of the list if no position is provided. The route is enabled by default. Stages a new version with the added route.

INSERT INTO vercel.project_routes.routes (
route,
position,
project_id,
team_id,
slug
)
SELECT 
'{{ route }}' /* required */,
'{{ position }}',
'{{ project_id }}',
'{{ team_id }}',
'{{ slug }}'
RETURNING
route,
version
;

Manifest

# Description fields are for documentation purposes
- name: routes
props:
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the routes resource.
  - name: route
    value:
      name: "{{ name }}"
      description: "{{ description }}"
      enabled: {{ enabled }}
      srcSyntax: "{{ srcSyntax }}"
      route:
        src: "{{ src }}"
        dest: "{{ dest }}"
        headers: "{{ headers }}"
        caseSensitive: {{ caseSensitive }}
        status: {{ status }}
        has:
          - type: "{{ type }}"
            key: "{{ key }}"
            value: "{{ value }}"
        missing:
          - type: "{{ type }}"
            key: "{{ key }}"
            value: "{{ value }}"
        transforms:
          - type: "{{ type }}"
            op: "{{ op }}"
            target: "{{ target }}"
            args: "{{ args }}"
            env: "{{ env }}"
        respectOriginCacheControl: {{ respectOriginCacheControl }}
  - name: position
    description: |
      Controls where the route is inserted. Defaults to "end" if omitted.
    value:
      placement: "{{ placement }}"
      referenceId: "{{ referenceId }}"
  - name: team_id
    value: "{{ team_id }}"
    description: The Team identifier to perform the request on behalf of.
    description: The Team identifier to perform the request on behalf of.
  - name: slug
    value: "{{ slug }}"
    description: The Team slug to perform the request on behalf of.
    description: The Team slug to perform the request on behalf of.

UPDATE examples

update

Replace a routing rule identified by its ID, or restore it from the current production version. Stages a new version with the modified route.

UPDATE vercel.project_routes.routes
SET 
route = '{{ route }}',
restore = {{ restore }}
WHERE 
project_id = '{{ project_id }}' --required
AND route_id = '{{ route_id }}' --required
AND team_id = '{{ team_id}}'
AND slug = '{{ slug}}'
RETURNING
route,
version;

REPLACE examples

stage

Stage routing rules for a project. Set overwrite to true to replace all existing rules, or omit it to merge with existing rules by ID. Returns the new staged version.

REPLACE vercel.project_routes.routes
SET 
overwrite = {{ overwrite }},
routes = '{{ routes }}'
WHERE 
project_id = '{{ project_id }}' --required
AND team_id = '{{ team_id}}'
AND slug = '{{ slug}}'
RETURNING
version;

DELETE examples

delete

Delete one or more routing rules from a project by ID. Stages a new version with the routes removed.

DELETE FROM vercel.project_routes.routes
WHERE project_id = '{{ project_id }}' --required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

generate

Generate a routing rule configuration from a natural language description. Returns a suggested route configuration that can be reviewed and saved.

EXEC vercel.project_routes.routes.generate 
@project_id='{{ project_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"prompt": "{{ prompt }}", 
"currentRoute": "{{ currentRoute }}"
}'
;