IONOS Domains API — Patched OpenAPI Spec

Reverse-engineered and patched OpenAPI 3.0.2 specification for the IONOS Domains API, including undocumented endpoints not present in the official spec.

What's in here

File	Description
ionos-domains-api.yaml	Full OpenAPI 3.0.2 spec (22 paths) with patched PUT nameservers endpoint
integrations.yaml	Composio custom tool integration config for API-KEY auth

The discovery

The official IONOS Domains API spec at developer.hosting.ionos.com/assets/kms-swagger-specs/domains.yaml only documents a GET method on /v1/domainitems/{domainId}/nameservers. Through experimentation, we discovered that PUT is also supported — it's just not in the spec.

Undocumented: PUT /v1/domainitems/{domainId}/nameservers

curl -X PUT "https://api.hosting.ionos.com/domains/v1/domainitems/{domainId}/nameservers" \
  -H "X-Api-Key: prefix.secret" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CUSTOM",
    "nameservers": [
      {"name": "apollo.ns.cloudflare.com"},
      {"name": "harleigh.ns.cloudflare.com"}
    ]
  }'

Response: 202 Accepted with {"id": "request-uuid"}

Poll GET /v1/requests/{id} until status is FINISHED.

Payload format

Field	Type	Required	Description
type	string	Yes	CUSTOM for external NS, DEFAULT to restore IONOS defaults
nameservers	array	Yes	Min 2 objects, each with a name string (the NS hostname)

What we tried that didn't work

Method	Status	Notes
PUT with [{"host": "ns"}]	400	Wrong field name — must be name, not host
PUT with [{"name": "ns"}] (bare array)	400	Must be wrapped in {type, nameservers}
POST	405	Not allowed
PATCH	405	Not allowed

API Authentication

Generate an API key at developer.hosting.ionos.com/keys. Format: prefix.secret.

# Header
X-Api-Key: bd103d36...secret_here

All documented endpoints

Method	Path	Description
GET	/v1/domainitems	List all domain items
GET	/v1/domainitems/domains	List domains with pagination
GET	/v1/domainitems/{domainId}	Get domain details
GET	/v1/domainitems/{domainId}/contacts	Get domain contacts
PUT	/v1/domainitems/{domainId}/contacts	Update domain contacts
GET	/v1/domainitems/{domainId}/registrycontacts	Get registry contacts
GET	/v1/domainitems/{domainId}/nameservers	Get nameservers
PUT	/v1/domainitems/{domainId}/nameservers	Update nameservers (undocumented)
GET	/v1/domainitems/{domainId}/statuses	Get domain statuses
PUT	/v1/domainitems/{domainId}/statuses	Update domain statuses
GET	/v1/domainitems/{domainId}/dnssec	Get DNSSEC config
PUT	/v1/domainitems/{domainId}/dnssec	Update DNSSEC config
PUT	/v1/domainitems/{domainId}/privacy	Update WHOIS privacy
PUT	/v1/domainitems/{domainId}/authcode	Request auth code
GET	/v1/requests/{requestId}	Poll async request status
POST	/v1/validation/domains	Validate domain availability
POST	/v1/validation/{tld}/contacts	Validate contacts for TLD
GET	/v1/tlds/{tld}	Get TLD info
GET	/v1/domainitems/tlds	List available TLDs
PUT	/v1/domainitems/{domainId}/transfer_in	Initiate inbound transfer
PUT	/v1/domainitems/{domainId}/transfer_out	Initiate outbound transfer
GET	/v1/domainitems/transfers	List pending transfers
POST	/v1/domainitems/preregistrations	Pre-register a domain
PUT	/v1/domainitems/{domainId}/email_verification	Trigger email verification
PUT	/v1/domainitems/{domainId}/data_quality	Update data quality
GET	/v1/domainitems/{domainId}/ownership	Get ownership info

Composio / Rube.app integration

The integrations.yaml file is configured for Composio's custom tool import (OpenAPI spec + integration config). Upload both files if/when Composio re-enables custom app registration via OpenAPI spec.

A ready-to-use Rube recipe is also available: IONOS Domain Manager (rcp_VjJ5Oxv8r_Fx)

How the spec was found

The IONOS developer portal at developer.hosting.ionos.com is an Angular SPA that loads Swagger UI. The spec URL was extracted from the compiled JavaScript bundle:

SwaggerUIBundle({
  url: "assets/kms-swagger-specs/" + this.spec + ".yaml"
})

Three specs exist: dns.yaml, domains.yaml, and ssl.yaml.

License

The original API spec is IONOS's property. This patch adds documentation for observed API behavior.