---
title: "Create a DNS record"
method: POST
path: "/v2/domains/{domain}/records"
tags: ["dns"]
---

# Create a DNS record

`POST /v2/domains/{domain}/records`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v2/domains/{domain}/records`
- Auth: HTTP bearer

Creates a DNS record for a domain.

## Path parameters

- `domain` string, required: The domain used to create the DNS record.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- union
  - object
    - `type` 'A', required: Must be of type `A`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, ipv4, required: The record value must be a valid IPv4 address.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'AAAA', required: Must be of type `AAAA`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, ipv6, required: An AAAA record pointing to an IPv6 address.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'ALIAS', required: Must be of type `ALIAS`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, required: An ALIAS virtual record pointing to a hostname resolved to an A record on server side.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'CAA', required: Must be of type `CAA`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, required: A CAA record to specify which Certificate Authorities (CAs) are allowed to issue certificates for the domain.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'CNAME', required: Must be of type `CNAME`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string: A CNAME record mapping to another domain name.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'MX', required: Must be of type `MX`.
    - `name` string, required: A subdomain name or an empty string for the root domain.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, required: An MX record specifying the mail server responsible for accepting messages on behalf of the domain name.
    - `mxPriority` number, required
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'SRV', required: Must be of type `SRV`.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `srv` object, required
      - `priority` number, nullable, required
      - `weight` number, nullable, required
      - `port` number, nullable, required
      - `target` string, required
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'TXT', required: Must be of type `TXT`.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string, required: A TXT record containing arbitrary text.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'NS', required: Must be of type `NS`.
    - `name` string, required: A subdomain name.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `value` string: An NS domain value.
    - `comment` string: A comment to add context on what this DNS record is for
  - object
    - `type` 'HTTPS', required: Must be of type `HTTPS`.
    - `ttl` number: The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
    - `https` object, required
      - `priority` number, nullable, required
      - `target` string, required
      - `params` string
    - `comment` string: A comment to add context on what this DNS record is for

## Response `200`

Successful response showing the uid of the newly created DNS record.

- union
  - object
    - `uid` string
    - `updated` number, required
  - object
    - `uid` string, required: The id of the newly created DNS record

## 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.
- `402`: The account is missing a payment so payment method must be updated
- `403`: You do not have permission to access this resource.
- `404`
- `409`
- `410`

## Changes

- **2026-08-12** `b7b824605094`: 1 breaking
  - the response property `oneOf[subschema #1]/uid` became optional for the status `200`
- **2026-07-21** `2ae10ee9d21c`: 1 info
  - added the non-success response with the status `410`
- **2026-01-22** `c12186034433`: 2 breaking, 1 info
  - removed `subschema #7, subschema #8, subschema #10` from the request body `anyOf` list
  - request body became required
  - added `subschema #7, subschema #8, subschema #10` to the request body `anyOf` list
- **2025-03-19** `37b482c58c92`: 1 breaking, 3 info
  - removed `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5, subschema #6, subschema #7, subschema #8, subschema #9` from the request body `anyOf` list
  - added the new optional `query` request parameter `slug`
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5, subschema #6, subschema #7, subschema #8, subschema #9, subschema #10` to the request body `anyOf` list
  - added the new `HTTPS` enum value to the request property `type`
- **2022-12-06** `8eb562567170`: 2 info
  - added `subschema #9` to the request body `anyOf` list
  - added the new `NS` enum value to the request property `type`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v2/domains/:domain/records/post.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)