> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Route

> Creates a new route in your tenant

## Create Route

```text theme={"dark"}
POST /v1/routes
```

Creates a new route in your tenant.

### Request Body

| Field                 | Type      | Required | Description                                            |
| --------------------- | --------- | -------- | ------------------------------------------------------ |
| `name`                | string    | Yes      | Display name for the route                             |
| `target_base_url`     | string    | Yes      | The upstream API base URL to proxy requests to         |
| `base_environment`    | string    | No       | Default environment (defaults to `production`)         |
| `inject_headers_json` | object    | No       | Headers to inject into proxied requests                |
| `inject_body_json`    | object    | No       | Body fields to inject into proxied requests            |
| `injection_rules`     | object\[] | No       | Advanced injection rules for secrets                   |
| `ip_allowlist`        | string\[] | No       | IP addresses or CIDR ranges allowed to call this route |
| `method_configs`      | object    | No       | Per-HTTP-method configuration overrides                |
| `collection_id`       | string    | No       | Assign to a collection                                 |

### Response

Returns the newly created route record (the full `routes` table row, including all columns). Note this differs from the [Get Route](./get) response, which returns a projected shape with additional derived fields (`environment_override_count`, `payload_structure`, `injection_rules`, `ip_allowlist`, `data_plane_node_id`, and `configured_environments`) that are not included here. Call [Get Route](./get) to retrieve those fields.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/routes \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Payment Gateway",
      "target_base_url": "https://api.stripe.com/v1"
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/routes",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={
          "name": "Payment Gateway",
          "target_base_url": "https://api.stripe.com/v1"
      }
  )
  route = resp.json()
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/routes", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Payment Gateway",
      target_base_url: "https://api.stripe.com/v1"
    })
  });
  const route = await resp.json();
  ```
</CodeGroup>

### Errors

| Status | Type               | Description                                    |
| ------ | ------------------ | ---------------------------------------------- |
| 400    | `validation_error` | Missing required fields or invalid environment |
| 403    | `plan_limit`       | Route limit reached for your subscription plan |
| 409    | `conflict`         | A route with this name already exists          |