---
title: "Edit a routing rule"
method: PATCH
path: "/v1/projects/{projectId}/routes/{routeId}"
tags: ["project-routes"]
---

# Edit a routing rule

`PATCH /v1/projects/{projectId}/routes/{routeId}`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/projects/{projectId}/routes/{routeId}`
- Auth: HTTP bearer

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

## Path parameters

- `projectId` string, required
- `routeId` string, required

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `route` object: The full route object to replace the existing route with
    - `name` string, required
    - `description` string
    - `enabled` boolean
    - `srcSyntax` 'equals' | 'path-to-regexp' | 'regex': Pattern syntax type. If not provided, inferred from pattern.
    - `route` object, required
      - `src` string, required
      - `dest` string
      - `headers` object
      - `caseSensitive` boolean
      - `status` integer
      - `has` object[]
        - `type` 'host' | 'header' | 'cookie' | 'query'
        - `key` string
        - `value` string
      - `missing` object[]
        - `type` 'host' | 'header' | 'cookie' | 'query'
        - `key` string
        - `value` string
      - `transforms` object[]
        - `type` 'request.headers' | 'request.query' | 'response.headers'
        - `op` 'append' | 'set' | 'delete'
        - `target` object
        - `args` unknown
        - `env` string[]
      - `respectOriginCacheControl` boolean
  - `restore` boolean: If true, restores the staged route to the value in the production version.

## Response `200`

- object
  - `route` object
    - `description` string: Optional description of what the routing rule does.
    - `enabled` false | true: Whether the routing rule is enabled. Defaults to true.
    - `id` string, required: Unique identifier for the routing rule.
    - `name` string, required: Human-readable name for the routing rule.
    - `rawDest` string: Original destination provided by user.
    - `rawSrc` string: Original source pattern provided by user (path-to-regexp or regex). Used to display the user's input in API responses.
    - `route` object, required: The route definition from @vercel/routing-utils.
      - `caseSensitive` false | true
      - `check` false | true
      - `continue` false | true
      - `dest` string
      - `destination` union
        - string
        - object
          - `path` string: Routing-only path used to select a route inside the target service.
          - `service` string, required
          - `type` 'service': Optional explicit format marker. The destination is identified by the presence of `service`, so `type` is no longer required.
      - `env` string[]
      - `has` union[]
        - union
          - object
            - `type` 'host', required
            - `value` union, required
              - …
          - object
            - `key` string, required
            - `type` 'cookie' | 'header' | 'query', required
            - `value` union
              - …
      - `headers` object
      - `important` false | true
      - `locale` object
        - `cookie` string
        - `redirect` object
      - `methods` string[]
      - `middleware` number: A middleware index in the `middleware` key under the build result
      - `middlewarePath` string: A middleware key within the `output` key under the build result. Overrides a `middleware` definition.
      - `middlewareRawSrc` string[]: The original middleware matchers.
      - `missing` union[]
        - union
          - object
            - `type` 'host', required
            - `value` union, required
              - …
          - object
            - `key` string, required
            - `type` 'cookie' | 'header' | 'query', required
            - `value` union
              - …
      - `mitigate` object
        - `action` 'challenge' | 'deny', required
      - `override` false | true
      - `respectOriginCacheControl` false | true
      - `source` string: Aliases for `src`, `dest`, and `status`. These provide consistency with the `rewrites`, `redirects`, and `headers` fields which use `source`, `destination`, and `statusCode`. During normalization, the string forms are converted to their canonical forms (`src`, `dest`, `status`) and stripped from the route object. `destination` may also be a service-targeted object, in which case routing is delegated into the named service's internal route table and the object is preserved as-is (not folded into `dest`).
      - `src` string, required
      - `status` number
      - `statusCode` number
      - `transforms` union[]
        - union
          - object
            - `args` union
              - …
            - `env` string[]
            - `op` 'append' | 'delete' | 'set', required
            - `target` object, required
              - …
            - `type` 'request.headers' | 'request.query' | 'response.headers', required
          - object
            - `args` string, required
            - `env` string[]
            - `op` 'set', required
            - `type` 'request.path', required
    - `routeType` 'redirect' | 'rewrite' | 'set_status' | 'transform'
    - `srcSyntax` 'equals' | 'path-to-regexp' | 'regex': The syntax type of the source pattern. Determines how the pattern is compiled to regex.
    - `staged` false | true: 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.
  - `version` object, required: A version of routing rules stored in S3.
    - `alias` string: The staging alias for previewing this version.
    - `createdBy` string, required: The user who created this version.
    - `id` string, required: Unique identifier for the version.
    - `isLive` false | true: Whether this version is currently live in production.
    - `isStaging` false | true: Whether this version is staged and not yet promoted to production.
    - `lastModified` number, required: Timestamp of when this version was last modified.
    - `ruleCount` number: The number of routing rules in this version.
    - `s3Key` string, required: The S3 key where the routing rules are stored.

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `409`
- `410`
- `500`

## Changes

- **2026-07-21** `2ae10ee9d21c`: 1 info
  - added the non-success response with the status `410`
- **2026-07-08** `3ff660568354`: 6 breaking, 2 warning
  - the response property `route/route/destination/oneOf[subschema #2]/type` became optional for the status `200`
  - added `subschema #1, subschema #2` to the `route/route/transforms/items/` response property `oneOf` list for the response status `200`
  - the `route/route/transforms/items/` response's property type changed from `object` to no type for status `200`
  - removed the required property `route/route/transforms/items/op` from the response with the `200` status
  - …4 more
- **2026-06-11** `14b4658f819e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/projects/:projectId/routes/:routeId/patch.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)