{ "openapi": "3.1.0", "info": { "title": "NameOcean API", "version": "1.0.0", "description": "Domains, DNS, SSL and app servers. JSON in, JSON out. Every error is `{\"error\": \"\", \"code\": \"\"}`. Guide for AI agents: https://nameocean.net/llms.txt", "contact": { "url": "https://nameocean.net/developers/" } }, "servers": [ { "url": "https://nameocean.net/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Account, credit and the activity log." }, { "name": "Domains", "description": "Search, register, renew and manage domains." }, { "name": "DNS", "description": "Zones and records." }, { "name": "SSL", "description": "Free wildcard certificates." }, { "name": "Servers", "description": "App servers: ports and domain bindings." }, { "name": "Email hosting", "description": "Mailboxes, aliases and mailing lists on your paid mail domains (Mox)." }, { "name": "Email forwarding", "description": "Free forwarding and mail-to-webhook for domains registered at NameOcean." }, { "name": "Webhooks", "description": "Endpoints that receive account events: https://nameocean.net/developers/webhooks/" } ], "paths": { "/": { "get": { "operationId": "describeTheApi", "tags": [ "Account" ], "summary": "Describe the API", "description": "Endpoints, record types, TTL values and scopes, as JSON.\n\nNo scope needed.", "x-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "accountAndCredit", "tags": [ "Account" ], "summary": "Account and credit", "description": "Your email and account credit in USD.\n\nScopes: `account:read`.", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audit": { "get": { "operationId": "activityLog", "tags": [ "Account" ], "summary": "Activity log", "description": "What was done on the account through the API, the CLI and MCP (every write call, refused calls and transfer-code reads) and API key and app changes in the dashboard. Newest first; pass next_cursor as cursor for the next page.\n\nScopes: `account:read`.", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the previous page" }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "api", "cli", "mcp", "dashboard" ] } } ] } }, "/domains/check": { "get": { "operationId": "checkAvailabilityAndPrice", "tags": [ "Domains" ], "summary": "Check availability and price", "description": "Is a domain free to register, and what it costs.\n\nScopes: `domains:read`.", "x-scopes": [ "domains:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCheck" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "example": "example.com" }, { "name": "years", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } } ] } }, "/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List domains", "description": "Scopes: `domains:read`.", "x-scopes": [ "domains:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "registerADomain", "tags": [ "Domains" ], "summary": "Register a domain", "description": "Paid from account credit; 402 with code insufficient_credit when it is not enough. Premium names need accept_premium: true. Send an Idempotency-Key so a retry never registers twice.\n\nScopes: `domains:write`, `billing:write`.", "x-scopes": [ "domains:write", "billing:write" ], "responses": { "201": { "description": "Registered; its DNS zone is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credit (code insufficient_credit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "years": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "accept_premium": { "type": "boolean" } }, "required": [ "name" ] }, "example": { "name": "example.com", "years": 1 } } } } } }, "/domains/{name}": { "get": { "operationId": "getADomain", "tags": [ "Domains" ], "summary": "Get a domain", "description": "Nameservers, lock, auto-renew and SSL status.\n\nScopes: `domains:read`.", "x-scopes": [ "domains:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "patch": { "operationId": "changeAutoRenewOrLock", "tags": [ "Domains" ], "summary": "Change auto-renew or lock", "description": "Scopes: `domains:write`.", "x-scopes": [ "domains:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_renew": { "type": "boolean" }, "locked": { "type": "boolean" } }, "required": [] }, "example": { "auto_renew": true } } } } } }, "/domains/{name}/nameservers": { "put": { "operationId": "setNameservers", "tags": [ "Domains" ], "summary": "Set nameservers", "description": "Two to four hostnames, or \"nameocean\" for NameOcean DNS.\n\nScopes: `domains:write`.", "x-scopes": [ "domains:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nameservers": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 4 }, { "const": "nameocean" } ] } }, "required": [ "nameservers" ] }, "example": { "nameservers": [ "ns1.example.net", "ns2.example.net" ] } } } } } }, "/domains/{name}/renew": { "post": { "operationId": "renewOneYear", "tags": [ "Domains" ], "summary": "Renew one year", "description": "Paid from account credit, within 60 days of expiry. Send an Idempotency-Key.\n\nScopes: `domains:write`, `billing:write`.", "x-scopes": [ "domains:write", "billing:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "renewed": { "type": "string" }, "charged": { "type": "string", "description": "USD amount as a decimal string", "examples": [ "12.99" ] }, "credit": { "type": "string", "description": "USD amount as a decimal string", "examples": [ "12.99" ] } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credit (code insufficient_credit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/domains/{name}/auth-code": { "get": { "operationId": "getTheTransferCode", "tags": [ "Domains" ], "summary": "Get the transfer code", "description": "The EPP code to move the domain away.\n\nScopes: `domains:write`.", "x-scopes": [ "domains:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "auth_code": { "type": "string" } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] } }, "/dns": { "get": { "operationId": "listDnsZones", "tags": [ "DNS" ], "summary": "List DNS zones", "description": "Scopes: `dns:read`.", "x-scopes": [ "dns:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "zones": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "serial": { "type": "integer" } }, "required": [] } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createADnsZone", "tags": [ "DNS" ], "summary": "Create a DNS zone", "description": "Free. Point the domain's nameservers to ns1-ns4.nameocean.net to use it.\n\nScopes: `dns:write`.", "x-scopes": [ "dns:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "example": { "name": "example.com" } } } } } }, "/dns/{zone}/records": { "get": { "operationId": "listRecords", "tags": [ "DNS" ], "summary": "List records", "description": "Scopes: `dns:read`.", "x-scopes": [ "dns:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "zone": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "addARecord", "tags": [ "DNS" ], "summary": "Add a record", "description": "Scopes: `dns:write`.", "x-scopes": [ "dns:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "CNAME", "MX", "TXT", "SRV", "PTR", "REDIRECT" ] }, "hostname": { "type": "string", "description": "@ for the zone itself" }, "ip": { "type": "string", "description": "A (IPv4 or IPv6)" }, "target": { "type": "string", "description": "CNAME, MX, SRV, PTR, REDIRECT" }, "text": { "type": "string", "description": "TXT" }, "priority": { "type": "integer", "description": "MX, SRV" }, "weight": { "type": "integer", "description": "SRV" }, "port": { "type": "integer", "description": "SRV" }, "save_path": { "type": "boolean", "description": "REDIRECT: keep the path" }, "ttl": { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "1d" ], "default": "1h" } }, "required": [ "type", "hostname" ], "description": "The fields of the record type: A {hostname, ip, ttl}, CNAME {hostname, target, ttl}, MX {hostname, priority, target, ttl}, TXT {hostname, text, ttl}, SRV {hostname, priority, weight, port, target, ttl}, PTR {hostname, target, ttl}, REDIRECT {hostname, target, save_path}." }, "example": { "type": "A", "hostname": "@", "ip": "203.0.113.10", "ttl": "1h" } } } } } }, "/dns/{zone}/records/{type}/{id}": { "get": { "operationId": "getARecord", "tags": [ "DNS" ], "summary": "Get a record", "description": "Scopes: `dns:read`.", "x-scopes": [ "dns:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "type", "in": "path", "required": true, "description": "Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT", "schema": { "type": "string" }, "example": "A" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 } ] }, "patch": { "operationId": "changeARecord", "tags": [ "DNS" ], "summary": "Change a record", "description": "Send only the fields to change.\n\nScopes: `dns:write`.", "x-scopes": [ "dns:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "type", "in": "path", "required": true, "description": "Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT", "schema": { "type": "string" }, "example": "A" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "CNAME", "MX", "TXT", "SRV", "PTR", "REDIRECT" ] }, "hostname": { "type": "string", "description": "@ for the zone itself" }, "ip": { "type": "string", "description": "A (IPv4 or IPv6)" }, "target": { "type": "string", "description": "CNAME, MX, SRV, PTR, REDIRECT" }, "text": { "type": "string", "description": "TXT" }, "priority": { "type": "integer", "description": "MX, SRV" }, "weight": { "type": "integer", "description": "SRV" }, "port": { "type": "integer", "description": "SRV" }, "save_path": { "type": "boolean", "description": "REDIRECT: keep the path" }, "ttl": { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "1d" ], "default": "1h" } }, "required": [ "type", "hostname" ], "description": "The fields of the record type: A {hostname, ip, ttl}, CNAME {hostname, target, ttl}, MX {hostname, priority, target, ttl}, TXT {hostname, text, ttl}, SRV {hostname, priority, weight, port, target, ttl}, PTR {hostname, target, ttl}, REDIRECT {hostname, target, save_path}." }, "example": { "ip": "203.0.113.20" } } } } }, "put": { "operationId": "replaceARecord", "tags": [ "DNS" ], "summary": "Replace a record", "description": "Same as PATCH.\n\nScopes: `dns:write`.", "x-scopes": [ "dns:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "type", "in": "path", "required": true, "description": "Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT", "schema": { "type": "string" }, "example": "A" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "CNAME", "MX", "TXT", "SRV", "PTR", "REDIRECT" ] }, "hostname": { "type": "string", "description": "@ for the zone itself" }, "ip": { "type": "string", "description": "A (IPv4 or IPv6)" }, "target": { "type": "string", "description": "CNAME, MX, SRV, PTR, REDIRECT" }, "text": { "type": "string", "description": "TXT" }, "priority": { "type": "integer", "description": "MX, SRV" }, "weight": { "type": "integer", "description": "SRV" }, "port": { "type": "integer", "description": "SRV" }, "save_path": { "type": "boolean", "description": "REDIRECT: keep the path" }, "ttl": { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "1d" ], "default": "1h" } }, "required": [ "type", "hostname" ], "description": "The fields of the record type: A {hostname, ip, ttl}, CNAME {hostname, target, ttl}, MX {hostname, priority, target, ttl}, TXT {hostname, text, ttl}, SRV {hostname, priority, weight, port, target, ttl}, PTR {hostname, target, ttl}, REDIRECT {hostname, target, save_path}." } } } } }, "delete": { "operationId": "deleteARecord", "tags": [ "DNS" ], "summary": "Delete a record", "description": "Scopes: `dns:write`.", "x-scopes": [ "dns:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "type", "in": "path", "required": true, "description": "Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT", "schema": { "type": "string" }, "example": "A" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/ssl/{zone}": { "get": { "operationId": "certificateStatus", "tags": [ "SSL" ], "summary": "Certificate status", "description": "Scopes: `ssl:read`.", "x-scopes": [ "ssl:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "zone": { "type": "string" } }, "required": [] }, { "$ref": "#/components/schemas/Ssl" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "issueACertificate", "tags": [ "SSL" ], "summary": "Issue a certificate", "description": "Free wildcard Let's Encrypt certificate; the zone must use NameOcean nameservers. Poll GET until active.\n\nScopes: `ssl:write`.", "x-scopes": [ "ssl:write" ], "responses": { "202": { "description": "Issuing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ssl" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] }, "patch": { "operationId": "changeAutoRenew", "tags": [ "SSL" ], "summary": "Change auto-renew", "description": "Scopes: `ssl:write`.", "x-scopes": [ "ssl:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "zone": { "type": "string" } }, "required": [] }, { "$ref": "#/components/schemas/Ssl" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "zone", "in": "path", "required": true, "description": "DNS zone (domain) name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_renew": { "type": "boolean" } }, "required": [ "auto_renew" ] }, "example": { "auto_renew": true } } } } } }, "/email/domains": { "get": { "operationId": "listMailDomains", "tags": [ "Email hosting" ], "summary": "List mail domains", "description": "Domains with paid email hosting. Buying, upgrading and reactivating a plan is done in the dashboard.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/MailDomain" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email/domains/{domain}": { "get": { "operationId": "getAMailDomain", "tags": [ "Email hosting" ], "summary": "Get a mail domain", "description": "With its mailboxes, aliases, mailing lists and the IMAP/SMTP settings.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailDomain" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "patch": { "operationId": "changeMailAutoRenew", "tags": [ "Email hosting" ], "summary": "Change mail auto-renew", "description": "Scopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailDomain" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_renew": { "type": "boolean" } }, "required": [ "auto_renew" ] }, "example": { "auto_renew": true } } } } } }, "/email/domains/{domain}/dns-check": { "get": { "operationId": "checkMailDns", "tags": [ "Email hosting" ], "summary": "Check mail DNS", "description": "Looks up NS, MX, SPF, DKIM and DMARC now and compares them with what NameOcean mail needs.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsCheck" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] } }, "/email/domains/{domain}/mailboxes": { "get": { "operationId": "listMailboxes", "tags": [ "Email hosting" ], "summary": "List mailboxes", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "mailboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "createAMailbox", "tags": [ "Email hosting" ], "summary": "Create a mailbox", "description": "Without a password one is generated. The answer is the only time the password is returned. quota_gb comes out of the plan's storage (default 1).\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "full_name": { "type": "string" }, "password": { "type": "string" }, "quota_gb": { "type": "integer" } }, "required": [ "username" ] }, "example": { "username": "info", "full_name": "Info" } } } } } }, "/email/domains/{domain}/mailboxes/{username}": { "get": { "operationId": "getAMailbox", "tags": [ "Email hosting" ], "summary": "Get a mailbox", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "username", "in": "path", "required": true, "description": "Mailbox name, the part before @ (or the full address)", "schema": { "type": "string" }, "example": "info" } ] }, "patch": { "operationId": "changeAMailbox", "tags": [ "Email hosting" ], "summary": "Change a mailbox", "description": "Send only what changes.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "username", "in": "path", "required": true, "description": "Mailbox name, the part before @ (or the full address)", "schema": { "type": "string" }, "example": "info" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string" }, "quota_gb": { "type": "integer" } }, "required": [] }, "example": { "quota_gb": 5 } } } } }, "delete": { "operationId": "deleteAMailbox", "tags": [ "Email hosting" ], "summary": "Delete a mailbox", "description": "Deletes the mailbox, all its mail and its aliases. This can't be undone.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "username", "in": "path", "required": true, "description": "Mailbox name, the part before @ (or the full address)", "schema": { "type": "string" }, "example": "info" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/domains/{domain}/mailboxes/{username}/password": { "post": { "operationId": "setAMailboxPassword", "tags": [ "Email hosting" ], "summary": "Set a mailbox password", "description": "Sets the password you send, or generates one when you send none, and returns it.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "username", "in": "path", "required": true, "description": "Mailbox name, the part before @ (or the full address)", "schema": { "type": "string" }, "example": "info" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 8 } }, "required": [] }, "example": {} } } } } }, "/email/domains/{domain}/aliases": { "get": { "operationId": "listMailAliases", "tags": [ "Email hosting" ], "summary": "List mail aliases", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/MailAlias" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "addAMailAlias", "tags": [ "Email hosting" ], "summary": "Add a mail alias", "description": "Mail to alias is delivered to the mailbox. Both are on the same domain; send the full address or the part before @.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailAlias" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "string" }, "mailbox": { "type": "string" } }, "required": [ "alias", "mailbox" ] }, "example": { "alias": "sales", "mailbox": "info" } } } } } }, "/email/domains/{domain}/aliases/{alias}": { "delete": { "operationId": "deleteAMailAlias", "tags": [ "Email hosting" ], "summary": "Delete a mail alias", "description": "Scopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "alias", "in": "path", "required": true, "description": "Alias address, or the part before @", "schema": { "type": "string" }, "example": "sales" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/domains/{domain}/lists": { "get": { "operationId": "listMailingLists", "tags": [ "Email hosting" ], "summary": "List mailing lists", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/MailingList" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "createAMailingList", "tags": [ "Email hosting" ], "summary": "Create a mailing list", "description": "Mail to the list's address goes to every member (mailboxes of the domain).\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailingList" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" } } }, "required": [ "address" ] }, "example": { "address": "team", "members": [ "info", "sales" ] } } } } } }, "/email/domains/{domain}/lists/{address}": { "get": { "operationId": "getAMailingList", "tags": [ "Email hosting" ], "summary": "Get a mailing list", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailingList" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "address", "in": "path", "required": true, "description": "Mailing list address, or the part before @", "schema": { "type": "string" }, "example": "team" } ] }, "patch": { "operationId": "changeAMailingList", "tags": [ "Email hosting" ], "summary": "Change a mailing list", "description": "members replaces the whole member list.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailingList" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "address", "in": "path", "required": true, "description": "Mailing list address, or the part before @", "schema": { "type": "string" }, "example": "team" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" } } }, "required": [] }, "example": { "members": [ "info" ] } } } } }, "delete": { "operationId": "deleteAMailingList", "tags": [ "Email hosting" ], "summary": "Delete a mailing list", "description": "Scopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "address", "in": "path", "required": true, "description": "Mailing list address, or the part before @", "schema": { "type": "string" }, "example": "team" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding": { "get": { "operationId": "listForwardingDomains", "tags": [ "Email forwarding" ], "summary": "List forwarding domains", "description": "Every active domain registered in your account, with whether forwarding is on and, when off, why it can't be.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Forwarding" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email/forwarding/{domain}": { "get": { "operationId": "getForwarding", "tags": [ "Email forwarding" ], "summary": "Get forwarding", "description": "Aliases and mail webhooks.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forwarding" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "turnForwardingOn", "tags": [ "Email forwarding" ], "summary": "Turn forwarding on", "description": "Free for domains registered at NameOcean that use NameOcean nameservers. Writes the MX record; other MX records are removed only with replace_mx: true (otherwise 409 mx_records_exist).\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forwarding" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "replace_mx": { "type": "boolean" } }, "required": [] }, "example": { "replace_mx": false } } } } }, "delete": { "operationId": "turnForwardingOff", "tags": [ "Email forwarding" ], "summary": "Turn forwarding off", "description": "Removes the MX record; aliases are kept for when it is turned on again.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Turned off", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding/{domain}/aliases": { "get": { "operationId": "listForwardingAliases", "tags": [ "Email forwarding" ], "summary": "List forwarding aliases", "description": "Scopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardAlias" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "addAForwardingAlias", "tags": [ "Email forwarding" ], "summary": "Add a forwarding alias", "description": "localpart@domain forwards to `to`; * forwards every address without its own alias. An address not confirmed yet gets a mail with a link and a code; mail is forwarded once it is confirmed.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardAlias" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "localpart": { "type": "string" }, "to": { "type": "string" } }, "required": [ "localpart", "to" ] }, "example": { "localpart": "hello", "to": "me@gmail.com" } } } } } }, "/email/forwarding/{domain}/aliases/{localpart}": { "delete": { "operationId": "deleteAForwardingAlias", "tags": [ "Email forwarding" ], "summary": "Delete a forwarding alias", "description": "Use * (%2A) for the catch-all.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "localpart", "in": "path", "required": true, "description": "The part before @, or * (%2A) for the catch-all", "schema": { "type": "string" }, "example": "hello" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding/targets": { "get": { "operationId": "listForwardingTargets", "tags": [ "Email forwarding" ], "summary": "List forwarding targets", "description": "Addresses you forward to and whether they confirmed.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardTarget" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email/forwarding/targets/{id}/verify": { "post": { "operationId": "confirmAForwardingTarget", "tags": [ "Email forwarding" ], "summary": "Confirm a forwarding target", "description": "The 6-digit code from the confirmation mail.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardTarget" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "example": { "code": "123456" } } } } } }, "/email/forwarding/targets/{id}/resend": { "post": { "operationId": "resendAConfirmationCode", "tags": [ "Email forwarding" ], "summary": "Resend a confirmation code", "description": "At most 3 a day per address.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardTarget" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding/{domain}/messages": { "get": { "operationId": "listForwardedMail", "tags": [ "Email forwarding" ], "summary": "List forwarded mail", "description": "The last 30 days, newest first: headers and what happened, never the body.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardedMessage" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "forwarded", "spam", "quota", "release_requested", "released", "bounced", "loop", "failed" ] } } ] } }, "/email/forwarding/{domain}/messages/{message_id}/release": { "post": { "operationId": "forwardHeldMail", "tags": [ "Email forwarding" ], "summary": "Forward held mail", "description": "Forwards a message held as spam, over the daily limit or failed (releasable: true).\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "202": { "description": "Forwarding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardedMessage" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "message_id", "in": "path", "required": true, "description": "Message id (uuid)", "schema": { "type": "string" }, "example": "6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding/{domain}/webhooks": { "get": { "operationId": "listMailWebhooks", "tags": [ "Email forwarding" ], "summary": "List mail webhooks", "description": "Addresses whose mail is posted to your URL as JSON, with their signing secrets.\n\nScopes: `email:read`.", "x-scopes": [ "email:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/MailWebhook" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" } ] }, "post": { "operationId": "addAMailWebhook", "tags": [ "Email forwarding" ], "summary": "Add a mail webhook", "description": "Mail to localpart@domain is posted to url as JSON (an email.received event). Open after a short review (403 not_approved until then); ask for it in the dashboard.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailWebhook" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "localpart": { "type": "string" }, "url": { "type": "string" } }, "required": [ "localpart", "url" ] }, "example": { "localpart": "inbound", "url": "https://example.com/hooks/mail" } } } } } }, "/email/forwarding/{domain}/webhooks/{localpart}": { "delete": { "operationId": "deleteAMailWebhook", "tags": [ "Email forwarding" ], "summary": "Delete a mail webhook", "description": "Scopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "localpart", "in": "path", "required": true, "description": "The part before @, or * (%2A) for the catch-all", "schema": { "type": "string" }, "example": "hello" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/email/forwarding/{domain}/webhooks/{localpart}/rotate-secret": { "post": { "operationId": "rotateAMailWebhookSecret", "tags": [ "Email forwarding" ], "summary": "Rotate a mail webhook secret", "description": "The old secret stops working at once.\n\nScopes: `email:write`.", "x-scopes": [ "email:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailWebhook" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name", "schema": { "type": "string" }, "example": "example.com" }, { "name": "localpart", "in": "path", "required": true, "description": "The part before @, or * (%2A) for the catch-all", "schema": { "type": "string" }, "example": "hello" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/webhooks/events": { "get": { "operationId": "listEventTypes", "tags": [ "Webhooks" ], "summary": "List event types", "description": "Every event type and group you can subscribe to.\n\nScopes: `webhooks:read`.", "x-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" } }, "required": [] } }, "groups": { "type": "array", "items": { "type": "string" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Scopes: `webhooks:read`.", "x-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addAWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Add a webhook endpoint", "description": "An https URL on a public server. The answer includes the signing secret. Up to 10 endpoints.\n\nScopes: `webhooks:write`.", "x-scopes": [ "webhooks:write" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } }, "required": [ "url", "events" ] }, "example": { "url": "https://example.com/hooks/nameocean", "events": [ "dns.*", "ssl.issued" ] } } } } } }, "/webhooks/{id}": { "get": { "operationId": "getAWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "description": "With its signing secret.\n\nScopes: `webhooks:read`.", "x-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 } ] }, "patch": { "operationId": "changeAWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Change a webhook endpoint", "description": "Send only what changes. active: true turns a disabled endpoint back on.\n\nScopes: `webhooks:write`.", "x-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "active": { "type": "boolean" } }, "required": [] }, "example": { "active": true } } } } }, "delete": { "operationId": "deleteAWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Scopes: `webhooks:write`.", "x-scopes": [ "webhooks:write" ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/webhooks/{id}/test": { "post": { "operationId": "sendATestEvent", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Posts a webhook.test event now, whatever the endpoint's event filter, and returns the delivery.\n\nScopes: `webhooks:write`.", "x-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listDeliveries", "tags": [ "Webhooks" ], "summary": "List deliveries", "description": "Newest first; pass next_cursor as cursor for the next page.\n\nScopes: `webhooks:read`.", "x-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] } } ] } }, "/webhooks/{id}/deliveries/{delivery_id}/resend": { "post": { "operationId": "resendADelivery", "tags": [ "Webhooks" ], "summary": "Resend a delivery", "description": "Posts the same event (same id) again now.\n\nScopes: `webhooks:write`.", "x-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "delivery_id", "in": "path", "required": true, "description": "Delivery id (whd_...)", "schema": { "type": "string" }, "example": "whd_3f9a1c2e4b5d6a7c8e9f0a1b" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/servers": { "get": { "operationId": "listAppServers", "tags": [ "Servers" ], "summary": "List app servers", "description": "Scopes: `servers:read`.", "x-scopes": [ "servers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/Server" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}": { "get": { "operationId": "getAServer", "tags": [ "Servers" ], "summary": "Get a server", "description": "SSH, git remote, ports and domains.\n\nScopes: `servers:read`.", "x-scopes": [ "servers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Server" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" } ] } }, "/servers/{server}/ports": { "get": { "operationId": "listOpenPorts", "tags": [ "Servers" ], "summary": "List open ports", "description": "Scopes: `servers:read`.", "x-scopes": [ "servers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "string" }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/Port" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" } ] }, "post": { "operationId": "openAPort", "tags": [ "Servers" ], "summary": "Open a port", "description": "The external port is assigned.\n\nScopes: `servers:write`.", "x-scopes": [ "servers:write" ], "responses": { "201": { "description": "Opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Port" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" } }, "required": [ "port" ] }, "example": { "port": 25565, "protocol": "tcp" } } } } } }, "/servers/{server}/ports/{id}": { "delete": { "operationId": "closeAPort", "tags": [ "Servers" ], "summary": "Close a port", "description": "Scopes: `servers:write`.", "x-scopes": [ "servers:write" ], "responses": { "204": { "description": "Closed", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } }, "/servers/{server}/domains": { "get": { "operationId": "listBoundDomains", "tags": [ "Servers" ], "summary": "List bound domains", "description": "Scopes: `servers:read`.", "x-scopes": [ "servers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "string" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Binding" } } }, "required": [] } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" } ] }, "post": { "operationId": "bindADomain", "tags": [ "Servers" ], "summary": "Bind a domain", "description": "Serves a domain or subdomain from the server: DNS records, SSL and the load balancer. Poll GET until status is active.\n\nScopes: `servers:write`, `dns:write`.", "x-scopes": [ "servers:write", "dns:write" ], "responses": { "201": { "description": "Setting up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Binding" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "subdomain": { "type": "string" } }, "required": [ "domain" ] }, "example": { "domain": "app.example.com" } } } } } }, "/servers/{server}/domains/{id}": { "delete": { "operationId": "unbindADomain", "tags": [ "Servers" ], "summary": "Unbind a domain", "description": "Scopes: `servers:write`, `dns:write`.", "x-scopes": [ "servers:write", "dns:write" ], "responses": { "204": { "description": "Unbound", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until a request slot frees up.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input (codes invalid_request, invalid_field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired key (code unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks a scope (code missing_scope, with required_scopes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your account (code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over 120 requests a minute (code rate_limited, with retry_after).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id, or its default domain such as 3f9a1c2e.nameocean.org", "schema": { "type": "string" }, "example": "3f9a1c2e" }, { "name": "id", "in": "path", "required": true, "description": "Numeric id", "schema": { "type": "integer" }, "example": 42 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (a UUID). A retry with the same key and request gets the first successful answer back, with Idempotent-Replayed: true, for 24 hours. Errors are not kept, so a retry after one runs again." } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from https://nameocean.net/dashboard/api/ (no_live_...) or an OAuth access token. Keys carry scopes: account:read, domains:read, domains:write, dns:read, dns:write, ssl:read, ssl:write, servers:read, servers:write, email:read, email:write, webhooks:read, webhooks:write, billing:write." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong and how to fix it, in words." }, "code": { "type": "string", "description": "Stable identifier to branch on: invalid_request, invalid_field, unauthorized, forbidden, missing_scope, not_found, conflict, already_exists, insufficient_credit, domain_unavailable, premium_not_accepted, email_not_confirmed, contact_details_missing, renewed_recently, nameservers_not_nameocean, rate_limited, idempotency_key_reused, idempotency_in_progress, upstream_error, unavailable, limit_reached, not_eligible, mx_records_exist, forwarding_off, invalid_code, refused, not_approved." }, "field": { "type": "string", "description": "The input at fault, when there is one." }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "With code missing_scope." }, "retry_after": { "type": "integer", "description": "Seconds, with code rate_limited." } }, "required": [ "error", "code" ] }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "channel": { "type": "string", "enum": [ "api", "cli", "mcp", "dashboard" ] }, "actor": { "type": "string", "description": "API key \"name\", the OAuth app, \"Old account key\" or \"Signed-in session\"" }, "action": { "type": "string", "description": "e.g. Add a record" }, "method": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "target": { "type": [ "string", "null" ], "description": "Domain, zone or server acted on" }, "result": { "type": "string", "enum": [ "ok", "denied", "error" ] }, "status_code": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "detail": { "type": "object", "description": "Path parameters, request body, error message" }, "ip": { "type": [ "string", "null" ] } }, "required": [] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types, groups like \"dns.*\", or [\"*\"]" }, "active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ], "description": "Why NameOcean turned it off" }, "secret": { "type": "string", "description": "whsec_...: verify X-NameOcean-Signature with it. Not in list answers." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "whd_..., also sent as X-NameOcean-Delivery" }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ], "description": "First 500 characters" }, "error": { "type": [ "string", "null" ] } }, "required": [] }, "Account": { "type": "object", "properties": { "email": { "type": "string" }, "credit": { "type": "string", "description": "USD amount as a decimal string", "examples": [ "12.99" ] }, "currency": { "const": "USD" }, "domains": { "type": "integer" }, "dns_zones": { "type": "integer" }, "add_funds_url": { "type": "string" } }, "required": [] }, "DomainCheck": { "type": "object", "properties": { "name": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": "string", "description": "Why it is not available." }, "years": { "type": "integer" }, "premium": { "type": "boolean" }, "register_price": { "type": "string", "description": "USD amount as a decimal string", "examples": [ "12.99" ] }, "renew_price": { "type": "string", "description": "USD amount as a decimal string", "examples": [ "12.99" ] }, "currency": { "const": "USD" } }, "required": [] }, "Ssl": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "none", "issuing", "waiting_for_nameservers", "active" ] }, "auto_renew": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": [ "string", "null" ] } }, "required": [] }, "Domain": { "type": "object", "properties": { "name": { "type": "string" }, "active": { "type": "boolean" }, "pending": { "type": "boolean" }, "suspended": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date-time" }, "auto_renew": { "type": "boolean" }, "locked": { "type": "boolean" } }, "required": [] }, "DomainDetail": { "allOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "renewal_price": { "type": [ "string", "null" ] }, "nameservers": { "type": "array", "items": { "type": "string" } }, "custom_nameservers": { "type": "boolean" }, "dns_zone": { "type": "boolean" }, "ssl": { "$ref": "#/components/schemas/Ssl" } }, "required": [] } ] }, "Record": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "A", "CNAME", "MX", "TXT", "SRV", "PTR", "REDIRECT" ] }, "hostname": { "type": "string", "description": "@ for the zone itself" }, "ip": { "type": "string", "description": "A (IPv4 or IPv6)" }, "target": { "type": "string", "description": "CNAME, MX, SRV, PTR, REDIRECT" }, "text": { "type": "string", "description": "TXT" }, "priority": { "type": "integer", "description": "MX, SRV" }, "weight": { "type": "integer", "description": "SRV" }, "port": { "type": "integer", "description": "SRV" }, "save_path": { "type": "boolean", "description": "REDIRECT: keep the path" }, "ttl": { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "1d" ], "default": "1h" } }, "required": [ "id", "type", "hostname" ] }, "Zone": { "type": "object", "properties": { "name": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "hint": { "type": "string" } }, "required": [] }, "Port": { "type": "object", "properties": { "id": { "type": "integer" }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ] }, "internal_port": { "type": "integer" }, "external_port": { "type": "integer" }, "connect_to": { "type": "string", "description": "Only when the port was just opened." } }, "required": [] }, "Binding": { "type": "object", "properties": { "id": { "type": "integer" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "setting_up", "active" ] }, "url": { "type": "string" } }, "required": [] }, "Server": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": [ "string", "null" ] }, "default_domain": { "type": "string" }, "cpu": { "type": "integer" }, "memory_mb": { "type": "integer" }, "disk_gb": { "type": "integer" }, "private_ip": { "type": [ "string", "null" ] }, "ipv6": { "type": [ "string", "null" ] }, "ssh": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "user": { "type": "string" }, "command": { "type": "string" } }, "required": [] }, "git_remote": { "type": [ "string", "null" ] }, "backups": { "type": "boolean" }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/Port" } }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Binding" } } }, "required": [] }, "MailDomain": { "type": "object", "properties": { "domain": { "type": "string" }, "active": { "type": "boolean" }, "suspended_reason": { "type": [ "string", "null" ], "enum": [ "unpaid", "ended", "admin", null ] }, "plan": { "type": [ "string", "null" ] }, "storage_gb": { "type": "integer" }, "used_gb": { "type": "string", "description": "Decimal GB, as of the last refresh" }, "assigned_gb": { "type": "integer", "description": "Sum of the mailboxes' quotas (at most storage_gb)" }, "max_mailboxes": { "type": [ "integer", "null" ] }, "mailbox_count": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "auto_renew": { "type": "boolean" }, "dashboard": { "type": "string" }, "mailboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" }, "description": "Only on GET /email/domains/{domain}" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/MailAlias" } }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/MailingList" } }, "settings": { "type": "object", "description": "IMAP, SMTP and webmail for mail clients" } }, "required": [] }, "Mailbox": { "type": "object", "properties": { "address": { "type": "string" }, "username": { "type": "string" }, "full_name": { "type": "string" }, "quota_gb": { "type": "integer" }, "used_gb": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "password": { "type": "string", "description": "Only in the answer that set it" } }, "required": [] }, "MailAlias": { "type": "object", "properties": { "address": { "type": "string" }, "mailbox": { "type": "string", "description": "The mailbox that receives it" } }, "required": [] }, "MailingList": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" } } }, "required": [] }, "DnsCheck": { "type": "object", "properties": { "domain": { "type": "string" }, "ok": { "type": "boolean" }, "checks": { "type": "object", "description": "ns, mx, spf, dkim, dmarc", "additionalProperties": { "type": "object", "properties": { "expected": {}, "current": {}, "ok": { "type": "boolean" } }, "required": [] } } }, "required": [] }, "Forwarding": { "type": "object", "properties": { "domain": { "type": "string" }, "active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "problems": { "type": "array", "items": { "type": "string" }, "description": "Why it can't be turned on, when it is off" }, "alias_count": { "type": "integer" }, "webhook_count": { "type": "integer" }, "mx": { "type": "string", "description": "The MX host forwarding writes into the zone" }, "max_aliases": { "type": "integer" }, "max_webhooks": { "type": "integer" }, "daily_limit": { "type": "integer", "description": "Mails forwarded per domain and day" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardAlias" } }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/MailWebhook" } } }, "required": [] }, "ForwardAlias": { "type": "object", "properties": { "localpart": { "type": "string", "description": "* = every address without its own alias" }, "address": { "type": "string" }, "catch_all": { "type": "boolean" }, "to": { "type": "string" }, "to_status": { "type": "string", "enum": [ "pending", "confirmed", "refused" ] }, "active": { "type": "boolean" }, "note": { "type": "string", "description": "Only when just added: what happens next" } }, "required": [] }, "ForwardTarget": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "refused" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [] }, "MailWebhook": { "type": "object", "properties": { "localpart": { "type": "string" }, "address": { "type": "string" }, "catch_all": { "type": "boolean" }, "url": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "whsec_...; signs X-NameOcean-Signature" } }, "required": [] }, "ForwardedMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": "string" }, "forwarded_to": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "status": { "type": "string", "enum": [ "forwarded", "spam", "quota", "release_requested", "released", "bounced", "loop", "failed" ] }, "spam_score": { "type": [ "number", "null" ] }, "releasable": { "type": "boolean" }, "smtp_response": { "type": [ "string", "null" ] } }, "required": [] } } } }