---
title: stage-routing-rules
product: vercel
url: /docs/rest-api/project-routes/stage-routing-rules
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about stage-routing-rules on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Stage routing rules

```http
PUT /v1/projects/{projectId}/routes
```

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.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `projectId` | string | Yes |  |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `teamId` | string | No | The Team identifier to perform the request on behalf of. |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Request body

Required: No

Content-Type: `application/json`

```json
{
  "type": "object",
  "properties": {
    "overwrite": {
      "type": "boolean"
    },
    "routes": {
      "type": "array",
      "default": [],
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "route"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 256
          },
          "name": {
            "type": "string",
            "maxLength": 256
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          },
          "enabled": {
            "type": "boolean"
          },
          "route": {
            "type": "object",
            "required": [
              "src"
            ],
            "properties": {
              "src": {
                "type": "string"
              },
              "dest": {
                "type": "string"
              },
              "headers": {
                "type": "object"
              },
              "caseSensitive": {
                "type": "boolean"
              },
              "status": {
                "type": "integer"
              },
              "has": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "host",
                        "header",
                        "cookie",
                        "query"
                      ]
                    },
                    "key": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  }
                }
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "host",
                        "header",
                        "cookie",
                        "query"
                      ]
                    },
                    "key": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  }
                }
              },
              "transforms": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "request.headers",
                        "request.query",
                        "response.headers"
                      ]
                    },
                    "op": {
                      "type": "string",
                      "enum": [
                        "append",
                        "set",
                        "delete"
                      ]
                    },
                    "target": {
                      "type": "object"
                    },
                    "args": {},
                    "env": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "respectOriginCacheControl": {
                "type": "boolean"
              }
            }
          }
        }
      }
    }
  }
}
```

## Responses

### 200: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "version": {
      "type": "object",
      "description": "A version of routing rules stored in S3.",
      "required": [
        "createdBy",
        "id",
        "lastModified",
        "s3Key"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the version."
        },
        "s3Key": {
          "type": "string",
          "description": "The S3 key where the routing rules are stored."
        },
        "lastModified": {
          "type": "number",
          "description": "Timestamp of when this version was last modified."
        },
        "createdBy": {
          "type": "string",
          "description": "The user who created this version."
        },
        "isStaging": {
          "type": "boolean",
          "description": "Whether this version is staged and not yet promoted to production.",
          "enum": [
            false,
            true
          ]
        },
        "isLive": {
          "type": "boolean",
          "description": "Whether this version is currently live in production.",
          "enum": [
            false,
            true
          ]
        },
        "ruleCount": {
          "type": "number",
          "description": "The number of routing rules in this version."
        },
        "alias": {
          "type": "string",
          "description": "The staging alias for previewing this version."
        }
      }
    }
  }
}
```

### 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.

---

## Related

- [project-routes endpoints](/docs/rest-api#project-routes)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)