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

# Add a routing rule

`POST /v1/projects/{projectId}/routes`

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.

## Path parameters

- `projectId` string, required

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `route` object, required
    - `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
  - `position` object — Controls where the route is inserted. Defaults to "end" if omitted.
    - `placement` 'start' | 'end' | 'after' | 'before' — "after"/"before" require referenceId.
    - `referenceId` string — Route ID to insert after/before. Required for "after"/"before".

## Response `200`

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

## 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.
- `409`
- `410`
- `500`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)