---
title: "Use Orgo DNS, or your own nameservers"
method: PUT
path: "/api/projects/{id}/domains/{domainId}/nameservers"
tags: ["domains"]
---

# Use Orgo DNS, or your own nameservers

`PUT /api/projects/{id}/domains/{domainId}/nameservers`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/projects/{id}/domains/{domainId}/nameservers`
- Auth: HTTP bearer

{ "mode": "orgo" } puts the domain on Orgo DNS, which serves the records in GET .../dns. { "mode": "custom", "nameservers": [...] } hands its DNS to another provider: 2 to 13 hostnames, lowercased, duplicates dropped. The records stay saved here but are not served, and every computer connected to the domain stops being reachable at it, so the switch is refused while any are (409 DOMAIN_IN_USE, with computers: their names) unless the body has "force": true.

Resolvers can take up to 48 hours to follow a nameserver change. A change the registry refuses is 502 NAMESERVERS_FAILED with its reason (a locked domain, for example). Needs write access, with a session, an account-wide key or a key for this workspace. Counts against the 60 DNS changes an hour.

## Path parameters

- `id` string, uuid, required
- `domainId` string, uuid, required

## Request body

- union
  - object
    - `mode` 'orgo', required
  - object
    - `mode` 'custom', required
    - `nameservers` string[], required
    - `force` boolean: Switch even while computers are connected to the domain.

## Response `200`

{ nameservers, serving }

- object
  - `nameservers` Nameservers, required
    - `mode` 'orgo' | 'custom', required: orgo: Orgo DNS serves the domain’s records. custom: another provider does.
    - `list` string[], required: The nameservers the registry has for the domain.
  - `serving` boolean, required

## Other responses

- `400`: Not 2 to 13 hostnames, or an unknown mode (INVALID_NAMESERVERS).
- `401`: Unauthenticated.
- `403`: View-only access (workspace_read_only), a key for another workspace (workspace_scope_mismatch), no access to the workspace (no code), or a share-link guest.
- `404`: Domains are not enabled for this account (DOMAINS_NOT_ENABLED), or the workspace has no such domain (DOMAIN_NOT_FOUND). A workspace you are not in answers 403.
- `409`: Computers are connected to the domain (DOMAIN_IN_USE, with computers); send force: true to switch anyway. Or DOMAIN_PENDING.
- `429`: Too many DNS changes this hour (RATE_LIMITED, with retry_after).
- `502`: The registry refused the change (NAMESERVERS_FAILED, with its reason), or did not answer (REGISTRAR_UNAVAILABLE).
- `503`: Domains are unavailable right now (DOMAINS_UNAVAILABLE).

## Changes

- **2026-11-01** `60e768a2bb9d`: 9 info
  - added the optional property `docs_url` to the response with the `400` status
  - added the optional property `docs_url` to the response with the `409` status
  - added the optional property `docs_url` to the response with the `502` status
  - added the optional property `next` to the response with the `400` status
  - …5 more
- **2026-10-22** `a506f6169bb5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/projects/:id/domains/:domainId/nameservers/put.md)

---

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