---
title: "Create a Tailscale Subnet Router"
method: POST
path: "/tailscale_subnet_routers"
tags: ["Tailscale Subnet Routers"]
---

# Create a Tailscale Subnet Router

`POST /tailscale_subnet_routers`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/tailscale_subnet_routers`
- Auth: HTTP bearer

Creates a Tailscale Subnet Router on a Network and enrolls it in the user's tailnet with the auth key. The response returns the router with `status` `provisioning`. Poll `GET /tailscale_subnet_routers/{id}` until it is `provisioned`. Then approve its routes in the tailnet, unless an auto-approver covers them.

## Request body

- TailscaleSubnetRouterCreate
  - `name` string, required: A user specified name for the router.
  - `network_id` string, uuid, required: The id of the Network to attach the router to.
  - `region_code` string, required: The code of the region to create the router in. `GET /network_coverage` lists the regions whose `available_services` include `tailscale_subnet_router`.
  - `advertised_routes` string[], required: IPv4 subnets of the Network that the router advertises to the tailnet. Each entry is a canonical CIDR that the Network routes. Default, loopback, link-local, multicast, and Tailscale (`100.64.0.0/10`) ranges are rejected. So are ranges that overlap the router's own, `172.27.254.0/24` and `198.18.0.0/20`.
  - `auth_key` string, password, required: A Tailscale auth key that enrolls the router in the user's tailnet: reusable, pre-approved, tagged, and not ephemeral. Telnyx stores it encrypted until enrollment succeeds, then discards it. It is never returned.

## Response `200`

Successful response. The router is created and provisioning has started.

- object
  - `data` TailscaleSubnetRouter
    - `id` string, uuid: Identifies the resource.
    - `record_type` string: Identifies the type of the resource.
    - `name` string: A user specified name for the router.
    - `network_id` string, uuid: The id of the Network the router is attached to.
    - `region_code` string: The code of the region the router is created in. `GET /network_coverage` lists the regions whose `available_services` include `tailscale_subnet_router`.
    - `advertised_routes` string[]: IPv4 subnets of the Network that the router advertises to the tailnet. Each entry is a canonical CIDR that the Network routes. Default, loopback, link-local, multicast, and Tailscale (`100.64.0.0/10`) ranges are rejected. So are ranges that overlap the router's own, `172.27.254.0/24` and `198.18.0.0/20`.
    - `status` 'provisioning' | 'provisioned' | 'failed' | 'deleting': `provisioning`: Telnyx is creating the router or applying a change. `provisioned`: the router is on the tailnet and advertises its routes; the tailnet still approves them. `failed`: enrollment did not complete, and `PATCH` retries it. `deleting`: the router is being removed.
    - `customer_address` string: The router's address on the Network, from `172.27.254.0/24`. Tailnet traffic enters the Network from this address.
    - `device_id` string, nullable: The router's node id on the tailnet. Set once the router has enrolled.
    - `tailnet_name` string, nullable: The name of the tailnet the router is enrolled in. Set once the router has enrolled.
    - `tailscale_ips` string[]: The router's addresses on the tailnet. Empty until the router has enrolled.
    - `created_at` string, date-time: ISO 8601 formatted date-time indicating when the resource was created.
    - `updated_at` string, date-time: ISO 8601 formatted date-time indicating when the resource was updated.

## Other responses

- `400`: Bad request: the body failed validation. `detail` says what failed, for example `Routes must exclude default, local, and Tailscale ranges.` or `The request contains unknown or read-only fields.`; a missing parameter or an unknown `network_id` or `region_code` names the field in `source.pointer`.
- `422`: Unprocessable entity: an advertised route overlaps the addresses reserved for routers, `172.27.254.0/24` and `198.18.0.0/20`. The body is the generic error; it does not name the route.
- `default`: Unexpected error

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-21** `b90f73c590c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/tailscale_subnet_routers/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)