{ "openapi": "3.0.3", "info": { "title": "Void API", "version": "1.0.0", "description": "Void REST API v1 — domains: availability and prices, registration, renewal, nameservers, Cloudflare zone, DNS records, settings and redirects. Authenticate with a bearer API key created in the Telegram bot (profile → API). Human docs: https://api.voidhosting.org/docs/" }, "servers": [ { "url": "https://api.voidhosting.org/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer void_…" } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domainName": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "EXPIRED", "FAILED" ] }, "nameservers": { "type": "array", "items": { "type": "string" } }, "price": { "type": "string" }, "renewalPrice": { "type": "string" }, "renewalYears": { "type": "integer" }, "autoRenew": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "blockFlags": { "type": "array", "items": { "type": "string" } } } }, "Availability": { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "price": { "type": "string", "nullable": true }, "reason": { "type": "string", "enum": [ "UNSUPPORTED_TLD", "UNCERTAIN" ] } } }, "DnsRecord": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "content": { "type": "string" }, "proxied": { "type": "boolean" }, "priority": { "type": "integer", "nullable": true } } }, "DnsInput": { "type": "object", "required": [ "type", "name", "content" ], "properties": { "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "TXT", "MX" ] }, "name": { "type": "string" }, "content": { "type": "string" }, "proxied": { "type": "boolean" }, "priority": { "type": "integer" } } }, "Settings": { "type": "object", "properties": { "ssl": { "type": "string", "enum": [ "off", "flexible", "full", "strict" ] }, "developmentMode": { "type": "boolean" }, "underAttack": { "type": "boolean" }, "alwaysOnline": { "type": "boolean" }, "botFightMode": { "type": "boolean" }, "regionBlock": { "type": "boolean" } } }, "Redirect": { "type": "object", "properties": { "id": { "type": "string" }, "match": { "type": "string" }, "target": { "type": "string" }, "permanent": { "type": "boolean" } } }, "Zone": { "type": "object", "properties": { "connected": { "type": "boolean" }, "domainName": { "type": "string" }, "zoneId": { "type": "string", "nullable": true }, "nameservers": { "type": "array", "items": { "type": "string" } }, "zoneStatus": { "type": "string", "enum": [ "none", "pending", "active", "moved" ] }, "nsApplied": { "type": "boolean" } } }, "RenewQuote": { "type": "object", "properties": { "domainId": { "type": "string" }, "domainName": { "type": "string" }, "price": { "type": "string" }, "years": { "type": "integer" }, "expiresAfter": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "failures": { "type": "integer" }, "lastStatus": { "type": "integer", "nullable": true }, "lastDeliveredAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "secret": { "type": "string", "description": "only in the create / rotate-secret response" } } }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "SENT", "FAILED" ] }, "attempts": { "type": "integer" }, "lastStatus": { "type": "integer", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "sentAt": { "type": "string", "nullable": true }, "nextAt": { "type": "string", "nullable": true } } } } }, "security": [ { "apiKey": [] } ], "paths": { "/me": { "get": { "summary": "Account", "responses": { "200": { "description": "balance and account id" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Account" ] } }, "/domains/tlds": { "get": { "summary": "Price list", "responses": { "200": { "description": "registration prices per TLD" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Availability" ] } }, "/domains/check": { "get": { "summary": "Check one name", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "availability + price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Availability" ] } }, "/domains/search": { "get": { "summary": "Search a bare name across all TLDs", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "list of Availability" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Availability" ] } }, "/domains": { "get": { "summary": "List your domains", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "items, total" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Domains" ] }, "post": { "summary": "Register a domain (charges the balance)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } } } } }, "responses": { "201": { "description": "Domain" }, "402": { "description": "INSUFFICIENT_FUNDS" }, "409": { "description": "DOMAIN_UNAVAILABLE" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Domains" ] } }, "/domains/{id}": { "get": { "summary": "One domain", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Domains" ] }, "patch": { "summary": "Change nameservers and/or auto-renew", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "nameservers": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 4 }, "autoRenew": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Domain" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Domains" ] } }, "/domains/{id}/renew-quote": { "get": { "summary": "Renewal price and new expiry", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "price, years, expiresAfter" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Renewal" ] } }, "/domains/{id}/renew": { "post": { "summary": "Renew (charges the balance)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain" }, "402": { "description": "INSUFFICIENT_FUNDS" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Renewal" ] } }, "/domains/{id}/cloudflare": { "get": { "summary": "Cloudflare zone status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "connected, nameservers, zoneStatus" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · zone" ] }, "post": { "summary": "Connect the domain to Cloudflare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "zone created; nameservers switched" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · zone" ] }, "delete": { "summary": "Disconnect from Cloudflare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "disconnected" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · zone" ] } }, "/domains/{id}/dns": { "get": { "summary": "DNS records (Cloudflare)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "list of DnsRecord" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · DNS" ] }, "post": { "summary": "Add a record", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsInput" } } } }, "responses": { "201": { "description": "DnsRecord" }, "409": { "description": "DNS_EXISTS" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · DNS" ] } }, "/domains/{id}/dns/{recordId}": { "put": { "summary": "Replace a record", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsInput" } } } }, "responses": { "200": { "description": "DnsRecord" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · DNS" ] }, "delete": { "summary": "Delete a record", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · DNS" ] } }, "/domains/{id}/cloudflare/refresh": { "post": { "summary": "Re-read zone status from Cloudflare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "zone status" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · zone" ] } }, "/domains/{id}/cloudflare/settings": { "get": { "summary": "Zone settings", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · settings" ] }, "patch": { "summary": "Change any subset of settings", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "responses": { "200": { "description": "Settings after the change" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · settings" ] } }, "/domains/{id}/cloudflare/purge": { "post": { "summary": "Purge the cache", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "purged" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · settings" ] } }, "/domains/{id}/cloudflare/redirects": { "get": { "summary": "Redirect rules", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "list of Redirect" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · redirects" ] }, "post": { "summary": "Add a redirect", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "match", "target" ], "properties": { "match": { "type": "string" }, "target": { "type": "string", "format": "uri" }, "permanent": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Redirect" }, "409": { "description": "REDIRECT_EXISTS / REDIRECT_LIMIT" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · redirects" ] } }, "/domains/{id}/cloudflare/redirects/{ruleId}": { "delete": { "summary": "Remove a redirect", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted" }, "401": { "description": "UNAUTHORIZED — missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED" } }, "tags": [ "Cloudflare · redirects" ] } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "Event names", "responses": { "200": { "description": "list of strings" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Your endpoints", "responses": { "200": { "description": "list of Webhook" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Add an endpoint (secret returned once)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Webhook with secret" }, "400": { "description": "VALIDATION_ERROR (non-https / private url)" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } }, "/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Enable / disable", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Webhook" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "deleted" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Queue a ping", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "deliveryId" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } }, "/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Issue a new secret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook with new secret" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Last 20 deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "list of Delivery" }, "401": { "description": "UNAUTHORIZED" }, "429": { "description": "RATE_LIMITED" } } } } }, "tags": [ { "name": "Account" }, { "name": "Availability", "description": "Prices and registry-verified availability checks" }, { "name": "Domains", "description": "Domains you own: list, register, nameservers, auto-renew" }, { "name": "Renewal" }, { "name": "Cloudflare · zone", "description": "Connect, disconnect, status" }, { "name": "Cloudflare · DNS" }, { "name": "Cloudflare · settings", "description": "SSL mode, security switches, cache" }, { "name": "Cloudflare · redirects" }, { "name": "Webhooks", "description": "Signed event callbacks: domain.blocked, domain.unblocked, domain.registered, domain.renewed, domain.expiring, domain.expired" } ] }