openapi: 3.1.0
info:
title: Web3 Partner API v3 account domain-management API
version: 3.0.0
contact:
name: Unstoppable Domains (Partner Engineering)
email: partnerengineering@unstoppabledomains.com
description: "# Feature Overview\nThe Web3 Partner API v3 provides you with the ability to lookup, register and manage Web3 domains. The API exposes a RESTful interface for interacting with Web3 domains and the Unstoppable Domains registry.\n- Lookup Domains: Search for specific domains or find suggested alternatives, to determine pricing, availability and on-chain details\n- Registering Domains: Secure domains into your dedicated Custody wallets to maintain the domains on the blockchain\n- Manage Domains: Update records on the blockchain or transfer the domain to external owners, all through a simple API interface\n\n## Custody Solution\nThe API takes the hassle of Web3 out of the equation. Unstoppable Domains will handle all blockchain interactions and concepts, while Partners simply use a RESTful API for managing domains.\n\nSince the domains will be in custody of the Partner, through Unstoppable Domains, the Partner is empowered to make any and all changes to the domains on behalf of their users.\n\nUnder the hood, Unstoppable Domains will manage dedicated custodial wallets for Partner-owned domains. These wallets are not shared between Partners and will uniquely identify the Partner on the various supported blockchains.\n\nShould the need arise to remove domains from custody, this is supported by changing the owner of domains to external owners.\n\n## Payments\nThe API will keep track of a running balance of charges and Unstoppable Domains will periodically invoice Partners to settle that balance. This empowers Partners to build payment processing in a way that works best for them.\n\n\n## Blockchain Support\nDomain details can be viewed across all of our supported blockchains:\n- Ethereum (ETH)\n- Polygon PoS (MATIC)\n- Base (BASE)\n\nDomains can **only be managed on Polygon PoS (MATIC) and Base (BASE)**. Domains on Ethereum (ETH) are readonly, but management support is coming soon.\n\n# Important Concepts\nThe API has some important concepts, in addition to Web3 Domains, that provide added utility, consistency and information.\n\n## Domain Ownership Type\nWeb3 domains exist on the supported Blockchains, and are owned by wallet addresses associated with those Blockchains. \nWe take ownership a step further, to provide improved security and reliability, by including an owner `type` in our ownership data.\nThe result is that a Domain's owner is defined by two values: `address` and `type`\n\nThe owner `type` can be one of the following:\n- `NONE`: Either the domain has never been owned or belongs to a \"burn\" address\n- `UD`: Owned by Unstoppable Domains\n- `SELF`: Domain belongs to a wallet addressed associated with your account, indicating you are able to manage it via the API\n- `EXTERNAL`: Owner doesn't qualify as any of the above. Changing to an `EXTERNAL` owner will result in the domain belonging to an address outside of the management of Unstoppable Domains and we will have no way to recover it.\n\nBy defining an owner in two parts (`address` and `type`) we ensure any irreversible action, such as transferring ownership, is deliberate and intended by requiring both the `address` and `type` in the request.\n\n## Operations\nAll interactions with the API that initiate changes will create an Operation for tracking that change.\nOperations can complete immediately or run in the background over the course of several minutes, depending on the Operation type and current conditions on the Blockchain.\n\nOperations include dependencies that represent the smaller units of work associated with the overall operation. These dependencies can also be tracked through the API and each have their own status and metadata.\n\nYour integration should properly handle and anticipate all of the following possible statuses for Operations and their dependencies:\n- `QUEUED` : The Operation has not started processing yet, but should be started shortly\n- `PROCESSING` : The Operation has started, often involving sending transactions to the Blockchain\n- `SIGNATURE_REQUIRED`: The operation is awaiting a signature in order to continue processing. This is only relevant to Self-Custody domain management.\n- `COMPLETED` : The Operation has finished processing successfully\n- `FAILED` : The Operation has finished processing and has either fully or partially failed\n- `CANCELLED` : The Operation has been cancelled, usually due to a failure with a sibling dependency\n\nSee the [Operations](/openapi/partner/v3/#tag/operations) API for additional information.\n\n## Wallets\nDomains ownership on the Blockchain is handled by associating a Domain with an \"address\". These addresses are typically managed by Wallets (usually in the form of an application on your computer or mobile device) that manage the private key for the public \"address\".\n\nThe API provides endpoints for creating/managing Wallets within your account to enable you to handle Domain ownership distribution in whatever way works for you. Any Domain that is owned by one of your account's Wallets is fully in your control to manage.\n\nSee the [Wallets](/openapi/partner/v3/#tag/wallets) API for additional information.\n\n# Get Access\nSee our quickstart guide for getting your Partner API key: [Set up Partner API Access](https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/)\n\nIf you have any questions, contact our [Partner Engineering Team](mailto:partnerengineering@unstoppabledomains.com?subject=Partner%20API%20v3%20Inquiry) to help with API access or learn more.\n"
servers:
- url: https://api.unstoppabledomains.com/partner/v3
description: Production
- url: https://api.ud-sandbox.com/partner/v3
description: Sandbox
security:
- bearer: []
tags:
- name: domain-management
description: 'Comprehensive domain updates — modify nameservers, DNSSEC, contacts, flags, and DNS records in a single request.
'
x-displayName: Domain Management
paths:
/domains/{name}:
patch:
operationId: updateDomain
summary: Update a domain
description: Comprehensive domain update — modify nameservers, DNSSEC, contacts, flags, and DNS records in a single operation. All fields are optional; only include the sections you want to change. Returns an operation that tracks all the resulting changes.
tags:
- domain-management
parameters:
- name: name
required: true
in: path
schema:
type: string
description: Domain name
- name: $preview
required: true
in: query
schema:
type: boolean
default: false
description: Preview mode — validate the request without executing changes.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DomainUpdateRequestBody'
responses:
'200':
description: Update operation created
content:
application/json:
schema:
$ref: '#/components/schemas/DomainOperationResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/mcp/v1/actions/ud_domain_auto_renewal_update:
post:
operationId: domainAutoRenewalUpdate
summary: Enable or disable auto renewal for ICANN DNS domains
description: Enable or disable auto renewal for ICANN DNS domains (.com, .net, .org, .io, etc.). When enabled, domains will be automatically renewed before expiration using the saved payment method. User must own the domains and have a valid payment method on file. Use ud_cart_get_payment_methods to retrieve available payment methods.
tags:
- domain-management
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
- domains
properties:
action:
type: string
enum:
- enable
- disable
description: 'Action to perform: "enable" or "disable" auto renewal'
domains:
type: array
items:
type: object
required:
- name
properties:
name:
type: string
description: Full domain name (e.g., "example.com")
minItems: 1
maxItems: 50
description: Array of domains to update auto renewal for
paymentMethodId:
type: string
description: Payment method ID for enabling. Use ud_cart_get_payment_methods to retrieve available payment methods. If not provided, uses default card.
responses:
'200':
description: Auto renewal update results
content:
application/json:
schema:
$ref: '#/components/schemas/AutoRenewalUpdateResponse'
'401':
description: Authentication required
/mcp/v1/actions/ud_domain_tags_add:
post:
operationId: domainTagsAdd
summary: Add tags to domains
description: Add tags to domains in your portfolio. Creates new tags automatically if they don't exist. Supports bulk operations for up to 50 domains.
tags:
- domain-management
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
- tags
properties:
domains:
type: array
items:
type: string
minLength: 1
minItems: 1
maxItems: 50
description: Array of domain names to add tags to (e.g., ["example.com", "mysite.io"])
example:
- example.com
- mysite.io
tags:
type: array
items:
type: string
minLength: 1
maxLength: 20
minItems: 1
maxItems: 10
description: Array of tag names to add (e.g., ["Work", "Important"]). Max 20 characters each.
example:
- Work
- Important
responses:
'200':
description: Tags added to domains
content:
application/json:
schema:
$ref: '#/components/schemas/AddDomainTagsResponse'
'401':
description: Authentication required
/mcp/v1/actions/ud_domain_tags_remove:
post:
operationId: domainTagsRemove
summary: Remove tags from domains
description: Remove tags from domains in your portfolio. Supports bulk operations for up to 50 domains.
tags:
- domain-management
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
- tags
properties:
domains:
type: array
items:
type: string
minLength: 1
minItems: 1
maxItems: 50
description: Array of domain names to remove tags from (e.g., ["example.com", "mysite.io"])
example:
- example.com
- mysite.io
tags:
type: array
items:
type: string
minLength: 1
minItems: 1
maxItems: 10
description: Array of tag names to remove (e.g., ["Work", "Old"])
example:
- Work
- Old
responses:
'200':
description: Tags removed from domains
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveDomainTagsResponse'
'401':
description: Authentication required
/mcp/v1/actions/ud_domain_flags_update:
post:
operationId: domainFlagsUpdate
summary: Update domain flags
description: Update domain flags (WHOIS privacy, transfer lock) for domains in your portfolio. Supports bulk operations for up to 50 domains.
tags:
- domain-management
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
- flags
properties:
domains:
type: array
items:
type: string
minLength: 1
minItems: 1
maxItems: 50
description: Array of domain names to update (e.g., ["example.com", "mysite.io"])
example:
- example.com
- mysite.io
flags:
type: object
description: Flags to update
properties:
DNS_TRANSFER_OUT:
type: object
properties:
status:
type: string
enum:
- ENABLED
- DISABLED
description: ENABLED = transfers allowed, DISABLED = transfers blocked
DNS_WHOIS_PROXY:
type: object
properties:
status:
type: string
enum:
- ENABLED
- DISABLED
description: ENABLED = personal info hidden, DISABLED = personal info public
responses:
'200':
description: Flags updated for domains
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDomainFlagsResponse'
'401':
description: Authentication required
/mcp/v1/actions/ud_domain_push:
post:
operationId: domainPush
summary: Push domains to another user
description: Push domains to another Unstoppable Domains user. Requires MFA (two-factor authentication) verification. The recipient must accept the transfer.
tags:
- domain-management
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
- targetAccountId
- otpCode
properties:
domains:
type: array
items:
type: string
minLength: 1
minItems: 1
maxItems: 50
description: Array of domain names to push (e.g., ["example.com", "mysite.io"])
example:
- example.com
- mysite.io
targetAccountId:
type: string
minLength: 1
description: Recipient's account ID in format "adjective-noun-xxx" (e.g., "brave-tiger-k7m")
example: brave-tiger-k7m
otpCode:
type: string
pattern: ^\d{6}$
description: 6-digit OTP code from your authenticator app
example: '123456'
responses:
'200':
description: Push initiated
content:
application/json:
schema:
$ref: '#/components/schemas/PushDomainsResponse'
'401':
description: Authentication required
components:
schemas:
PlatformOperationDnsRecordDelete:
type: object
description: Deletes a DNS record
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DNS_RECORD_DELETE
parameters:
type: object
properties:
id:
type: string
description: DNS record ID to delete
required:
- id
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
DomainFlagStatus:
type: string
enum:
- ENABLED
- DISABLED
ContactAssignment:
type: object
description: Reference to an existing or newly created contact
properties:
new:
type: boolean
description: Whether this contact is being newly created as part of this operation
id:
type: string
description: Contact ID (present when new is false)
example: con_abc12345-1234-1234-1234-abc123456789
required:
- new
PlatformOperationDnsRecordUpdate:
type: object
description: Updates an existing DNS record
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DNS_RECORD_UPDATE
parameters:
type: object
properties:
id:
type: string
description: DNS record ID to update
values:
type: array
items:
type: string
ttl:
type: integer
description: Time-to-live in seconds
required:
- id
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
DomainUpdateRequestBody:
type: object
description: Comprehensive domain update — change nameservers, DNSSEC, contacts, flags, and DNS records in a single request. All fields are optional; only include sections you want to change.
properties:
nameservers:
$ref: '#/components/schemas/DomainUpdateNameserversConfig'
dnssec:
$ref: '#/components/schemas/DomainUpdateDnssecConfig'
contacts:
$ref: '#/components/schemas/DomainContactUpdatesRequestBody'
flags:
$ref: '#/components/schemas/DomainFlagUpdateRequestBody'
records:
$ref: '#/components/schemas/DomainUpdateRecordsConfig'
DomainDnsSecruityCreateRequestBodyDnssec:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/DomainDnsSecruityCreateRequestBodyDnssecItem'
required:
- items
DomainUpdateDnssecConfig:
type: object
description: DNSSEC configuration for UD-managed nameservers. Enable or disable DNSSEC signing.
properties:
enabled:
type: boolean
description: Set to `true` to enable DNSSEC, `false` to disable.
$forceCompatibility:
type: boolean
default: false
description: Force compatibility mode when enabling DNSSEC.
required:
- enabled
PlatformOperationContactCreate:
type: object
description: Creates a new contact for use in domain registration or management
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- CONTACT_CREATE
parameters:
type: object
properties:
purposes:
type: array
items:
$ref: '#/components/schemas/ContactPurpose'
description: Intended roles for this contact
example:
- OWNER
- ADMIN
required:
- purposes
result:
type: object
properties:
id:
type: string
description: ID of the created contact
example: ct-a1b2c3d4-e5f6-7890-abcd-ef1234567890
required:
- id
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
RemoveDomainTagsResponse:
type: object
properties:
results:
type: array
items:
type: object
properties:
domain:
type: string
description: Domain name
success:
type: boolean
description: Whether tags were removed successfully
tagsRemoved:
type: array
items:
type: string
description: Tags that were removed from this domain
error:
type: string
description: Error message if failed
description: Results for each domain
successCount:
type: number
description: Number of domains with tags removed
failureCount:
type: number
description: Number of domains that failed
DomainOwnerContactTldSpecificRequestBody:
type: object
properties:
ca:
$ref: '#/components/schemas/DomainContactCiraRequestBody'
description: TLD-specific owner contact data. Currently only `.ca` (CIRA) is supported. Include the relevant TLD key only when registering a domain under that TLD.
PlatformOperationDomainDnsContactSet:
type: object
description: Updates contact role assignments for the domain
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DOMAIN_DNS_CONTACT_SET
parameters:
type: object
properties:
owner:
$ref: '#/components/schemas/ContactAssignment'
admin:
$ref: '#/components/schemas/ContactAssignment'
billing:
$ref: '#/components/schemas/ContactAssignment'
tech:
$ref: '#/components/schemas/ContactAssignment'
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
PlatformOperationDomainDnsSecurityDeleteDnssec:
type: object
description: Removes DNSSEC DS records from the registry for a domain
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DOMAIN_DNS_SECURITY_DELETE_DNSSEC
parameters:
type: object
properties:
domain:
type: string
description: Domain name
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
NonRegistrantContacts:
type: object
description: Non-registrant contact role assignments (admin, billing, tech)
properties:
admin:
$ref: '#/components/schemas/ContactAssignment'
billing:
$ref: '#/components/schemas/ContactAssignment'
tech:
$ref: '#/components/schemas/ContactAssignment'
PlatformOperationDomainFlagLockUpdate:
type: object
description: Updates domain flag lock settings (e.g., transfer lock, delete lock)
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DOMAIN_FLAG_LOCK_UPDATE
parameters:
type: object
properties:
locks:
$ref: '#/components/schemas/DomainFlagLocks'
policyLocks:
$ref: '#/components/schemas/DomainFlagLocks'
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
DomainUpdateNameserversConfig:
type: object
description: Nameserver configuration. Provide `items` to switch to custom nameservers, or set `$revertToManaged` to switch back to UD-managed nameservers. These options are mutually exclusive.
properties:
items:
type: array
items:
type: string
minItems: 1
maxItems: 20
uniqueItems: true
description: Custom nameserver hostnames.
example:
- ns1.example.com
- ns2.example.com
dnssec:
$ref: '#/components/schemas/DomainDnsSecruityCreateRequestBodyDnssec'
$revertToManaged:
type: boolean
description: Set to `true` to revert to UD-managed nameservers. Mutually exclusive with `items`.
ErrorResponse:
type: object
description: Standard error response
properties:
code:
type: string
description: Machine-readable error code
example: VALIDATION
message:
type: string
description: Human-readable error description
errors:
type: array
description: Individual errors when code is MULTIPLE_ERRORS
items:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
required:
- code
DomainFlagUpdateRequestBody:
type: object
properties:
DNS_RESOLUTION:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
DNS_TRANSFER_OUT:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
DNS_DELETE:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
DNS_UPDATE:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
DNS_RENEW:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
DNS_WHOIS_PROXY:
$ref: '#/components/schemas/DomainFlagUpdateRequestBodyFlag'
description: Update domain flag settings. Only include the flags you want to change — omitted flags remain unchanged.
UpdateDomainFlagsResponse:
type: object
properties:
results:
type: array
items:
type: object
properties:
domain:
type: string
description: Domain name
success:
type: boolean
description: Whether flags were updated successfully
updatedFlags:
type: array
items:
type: string
description: Flags that were updated for this domain
error:
type: string
description: Error message if failed
description: Results for each domain
successCount:
type: number
description: Number of domains with flags updated
failureCount:
type: number
description: Number of domains that failed
DnssecAlgorithm:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 10
- 12
- 13
- 14
- 15
- 16
- 17
- 23
- 252
- 253
- 254
description: DNSSEC algorithm identifier (RFC 8624)
ContactPurpose:
type: string
enum:
- OWNER
- ADMIN
- TECH
- BILLING
PlatformOperationDomainRegister:
type: object
description: Registers a new domain with the specified owner contact and optional role contacts
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
enum:
- DOMAIN_REGISTER
parameters:
type: object
properties:
owner:
$ref: '#/components/schemas/ContactAssignment'
contacts:
$ref: '#/components/schemas/NonRegistrantContacts'
period:
type: integer
description: Registration period in years
example: 1
required:
- owner
error:
$ref: '#/components/schemas/OperationDependencyError'
required:
- id
- '@type'
- status
- type
- parameters
PlatformOperationStatus:
type: string
enum:
- PREVIEW
- QUEUED
- PROCESSING
- FAILED
- COMPLETED
- CANCELLED
- AWAITING_UPDATES
description: Status of a platform operation dependency
CiraLanguageCode:
type: string
enum:
- en_US
- fr_CA
- en
- fr
description: CIRA preferred language code
PlatformOperationDomainDnsSecurityUpdateZone:
type: object
description: Updates the DNS zone configuration for DNSSEC signing
properties:
id:
type: string
example: plop_abc12345-1234-1234-1234-abc123456789
'@type':
type: string
enum:
- unstoppabledomains.com/partner.v3.PlatformOperation
status:
$ref: '#/components/schemas/PlatformOperationStatus'
type:
type: string
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unstoppable-domains/refs/heads/main/openapi/unstoppable-domains-domain-management-api-openapi.yml