{ "openapi": "3.1.0", "info": { "title": "VPSMetrics API Reference", "version": "v1", "description": "VPSMetrics API for authenticated access to account data, providers, benchmarks, and selected tools. Use a personal API key from your VPSMetrics account and send it as a Bearer token in the Authorization header." }, "servers": [ { "url": "https:\/\/vpsmetrics.com\/api\/v1" } ], "tags": [ { "name": "Profile", "description": "Authenticated profile and credit endpoints." }, { "name": "Providers", "description": "Provider list and provider detail endpoints." }, { "name": "Benchmarks", "description": "Benchmark collection and detail endpoints." }, { "name": "Tools", "description": "Tool execution endpoints available through scoped API keys." } ], "security": [ { "bearerAuth": [] } ], "paths": { "\/me": { "get": { "operationId": "me.show", "description": "Returns the authenticated user profile, the current token metadata, and the list of available API key abilities.\n\n**Required ability:** `read:profile`", "summary": "Get the authenticated account profile", "tags": [ "Profile" ], "responses": { "200": { "description": "Successful profile response", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Account data retrieved successfully." }, "data": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "data", "meta" ] } } } }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "object", "examples": [ "This API key does not have access to this endpoint." ], "properties": { "message": { "type": "string", "const": "This API key does not have access to this endpoint." }, "errors": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "errors", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "x-required-ability": "read:profile" } }, "\/me\/credits": { "get": { "operationId": "me.credits", "description": "Returns the current Tool Credit balance for the authenticated account.\n\n**Required ability:** `read:profile`", "summary": "Get the authenticated account Tool Credit balance", "tags": [ "Profile" ], "responses": { "200": { "description": "Successful credit response", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Credit balance retrieved successfully." }, "data": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "data", "meta" ] } } } }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "object", "examples": [ "This API key does not have access to this endpoint." ], "properties": { "message": { "type": "string", "const": "This API key does not have access to this endpoint." }, "errors": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "errors", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "x-required-ability": "read:profile" } }, "\/me\/billing": { "get": { "operationId": "me.billing", "description": "Returns the current API plan, API request usage, shared expensive-tool usage, and Tool Credit balance for the authenticated account.\n\n**Required ability:** `read:profile`", "summary": "Get the authenticated account billing summary", "tags": [ "Profile" ], "responses": { "200": { "description": "Successful billing response", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Billing summary retrieved successfully." }, "data": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "data", "meta" ] } } } }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "object", "examples": [ "This API key does not have access to this endpoint." ], "properties": { "message": { "type": "string", "const": "This API key does not have access to this endpoint." }, "errors": { "type": "string" }, "meta": { "type": "string" } }, "required": [ "message", "errors", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "x-required-ability": "read:profile" } }, "\/providers": { "get": { "operationId": "provider.index", "description": "Returns a paginated provider collection with optional search and country filtering. Requires an active API plan.\n\n**Required ability:** `read:providers`", "summary": "List VPS providers", "tags": [ "Providers" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "country_code", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated provider response", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Validation failed", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "read:providers" } }, "\/providers\/{slug}": { "get": { "operationId": "provider.show", "description": "Returns a single provider by slug, including related promos, features, and tags when available. Requires an active API plan.\n\n**Required ability:** `read:providers`", "summary": "Get provider detail", "tags": [ "Providers" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The provider slug.", "schema": { "type": "string" }, "example": "fixture-provider" } ], "responses": { "200": { "description": "Successful provider detail response", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "Provider not found", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "read:providers" } }, "\/benchmarks": { "get": { "operationId": "benchmark.index", "description": "Returns a paginated benchmark collection with provider, location, virtualization, IP support, date-range, and pagination filters. Requires an active API plan.\n\n**Required ability:** `read:benchmarks`", "summary": "List benchmark records", "tags": [ "Benchmarks" ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "location", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "virtualization", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "ipv4", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "ipv6", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "tested_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "tested_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated benchmark response", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Validation failed", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "read:benchmarks" } }, "\/benchmarks\/{slug}": { "get": { "operationId": "benchmark.show", "description": "Returns a single benchmark record by slug, including related provider, location, and benchmark result data. Requires an active API plan.\n\n**Required ability:** `read:benchmarks`", "summary": "Get benchmark detail", "tags": [ "Benchmarks" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The benchmark slug.", "schema": { "type": "string" }, "example": "fixture-provider-performance-2c4g-singapore" } ], "responses": { "200": { "description": "Successful benchmark detail response", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "Benchmark not found", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "read:benchmarks" } }, "\/tools\/whois": { "post": { "operationId": "tool.whois", "description": "Looks up registration data for a domain and returns either a summary or a more detailed WHOIS payload.\n\n**Required ability:** `tool:whois`", "summary": "Run a WHOIS lookup", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/WhoisLookupRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 }, "detail": { "type": "boolean", "description": "When true, return a more detailed WHOIS payload.", "example": false } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "WHOIS lookup result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:whois" } }, "\/tools\/dns-lookup": { "post": { "operationId": "tool.dnsLookup", "description": "Looks up DNS records for a domain and can return either a core or full result set.\n\n**Required ability:** `tool:dns-lookup`", "summary": "Run a DNS lookup", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/DnsLookupRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 }, "scope": { "type": [ "string", "null" ], "description": "Result scope. Allowed values: core, full.", "enum": [ "full", "core" ], "example": "full" } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "DNS lookup result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:dns-lookup" } }, "\/tools\/dns-propagation-checker": { "post": { "operationId": "tool.dnsPropagation", "description": "Checks the propagation state of a DNS record across external resolvers.\n\n**Required ability:** `tool:dns-propagation-checker`", "summary": "Check DNS propagation", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/DnsPropagationCheckRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 }, "record_type": { "type": [ "string", "null" ], "description": "DNS record type to check. Example: A, AAAA, MX, TXT.", "enum": [ "A", "AAAA", "MX", "NS", "TXT", "CNAME", "SOA", "CAA", "SRV", "PTR" ], "example": "A" }, "mode": { "type": [ "string", "null" ], "description": "Resolver mode. Example values include reliable.", "enum": [ "fast", "reliable", "comprehensive", "all" ], "example": "reliable" } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "DNS propagation result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:dns-propagation-checker" } }, "\/tools\/spf-checker": { "post": { "operationId": "tool.spf", "description": "Looks up and evaluates the SPF record for a domain.\n\n**Required ability:** `tool:spf-checker`", "summary": "Run an SPF lookup", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/SpfLookupRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "SPF lookup result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:spf-checker" } }, "\/tools\/dmarc-lookup": { "post": { "operationId": "tool.dmarc", "description": "Looks up and parses the DMARC record for a domain.\n\n**Required ability:** `tool:dmarc-lookup`", "summary": "Run a DMARC lookup", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/DmarcLookupRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "DMARC lookup result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:dmarc-lookup" } }, "\/tools\/what-is-my-ip": { "post": { "operationId": "tool.whatIsMyIp", "description": "Returns IP location data and can optionally include AbuseIPDB-based reputation metadata when configured.\n\n**Required ability:** `tool:what-is-my-ip`", "summary": "Look up IP metadata", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/WhatIsMyIpLookupRequest" }, { "type": "object", "properties": { "ip": { "type": [ "string", "null" ], "description": "Optional IP address to inspect. If omitted, VPSMetrics uses the request IP address.", "example": "8.8.8.8" }, "include_reputation": { "type": "boolean", "description": "Whether to include reputation data when available.", "example": true } } } ] } } } }, "responses": { "200": { "description": "IP lookup result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:what-is-my-ip" } }, "\/tools\/uptime-calculator": { "post": { "operationId": "tool.uptime", "description": "Calculates downtime from uptime or the inverse, depending on the selected mode.\n\n**Required ability:** `tool:uptime-calculator`", "summary": "Run the uptime calculator", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/UptimeCalculatorRequest" }, { "type": "object", "properties": { "mode": { "type": "string", "description": "Calculation mode. Allowed values: uptime, reverse.", "enum": [ "uptime", "reverse" ], "example": "uptime" }, "uptime": { "type": [ "number", "null" ], "description": "Required when mode is uptime.", "example": 99.95, "minimum": 0, "maximum": 100 }, "period": { "type": "string", "description": "Allowed values: daily, weekly, monthly, quarterly, yearly, custom.", "enum": [ "daily", "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly" }, "custom_days": { "type": [ "integer", "null" ], "description": "Required when period is custom.", "example": 45, "minimum": 1, "maximum": 3650 }, "downtime_amount": { "type": [ "number", "null" ], "description": "Required when mode is reverse.", "example": 30, "minimum": 0 }, "downtime_unit": { "type": "string", "description": "Allowed values: seconds, minutes, hours.", "enum": [ "seconds", "minutes", "hours" ], "example": "minutes" } }, "required": [ "mode", "period", "downtime_unit" ] } ] } } } }, "responses": { "200": { "description": "Uptime calculation result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:uptime-calculator" } }, "\/tools\/crontab-generator": { "post": { "operationId": "tool.crontab", "description": "Validates a cron expression, renders natural language output, and returns the next scheduled run times.\n\n**Required ability:** `tool:crontab-generator`", "summary": "Preview a crontab expression", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/CrontabPreviewRequest" }, { "type": "object", "properties": { "expression": { "type": "string", "description": "The cron expression to validate.", "example": "*\/5 * * * *", "maxLength": 255 }, "language": { "type": [ "string", "null" ], "description": "Natural language output language.", "enum": [ "en", "id" ], "example": "en" }, "timezone": { "type": [ "string", "null" ], "description": "Timezone used to calculate upcoming run times.", "example": "UTC" } }, "required": [ "expression" ] } ] } } } }, "responses": { "200": { "description": "Crontab preview result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:crontab-generator" } }, "\/tools\/csv-to-json": { "post": { "operationId": "tool.csvToJson", "description": "Converts a CSV payload into a JSON structure, optionally using the first row as a header row.\n\n**Required ability:** `tool:csv-to-json`", "summary": "Convert CSV to JSON", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/CsvToJsonRequest" }, { "type": "object", "properties": { "csv": { "type": "string", "description": "The CSV content to convert.", "example": "name,score\nAlice,10\nBob,20", "maxLength": 5000000 }, "delimiter": { "type": [ "string", "null" ], "description": "CSV delimiter character.", "example": ",", "minLength": 1, "maxLength": 1 }, "has_header": { "type": "boolean", "description": "Whether the first CSV row is a header row.", "example": true } }, "required": [ "csv" ] } ] } } } }, "responses": { "200": { "description": "CSV conversion result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:csv-to-json" } }, "\/tools\/ping": { "post": { "operationId": "tool.ping", "description": "Runs a ping measurement for a single target across either a named preset or a custom list of Globalping-compatible locations.\n\n**Required ability:** `tool:ping`", "summary": "Run a multi-location ping", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/PingRequest" }, { "type": "object", "properties": { "target": { "type": "string", "description": "The domain or IP address to ping.", "example": "example.com", "maxLength": 255 }, "packets": { "type": [ "integer", "null" ], "description": "Number of packets per probe. Allowed values: 1 to 10.", "example": 3, "minimum": 1, "maximum": 10 }, "limit": { "type": [ "integer", "null" ], "description": "Maximum probes per location selector. Allowed values: 1 to 5.", "example": 5, "minimum": 1, "maximum": 5 }, "preset": { "type": [ "string", "null" ], "description": "Named location preset. Provide exactly one of preset or locations.", "enum": [ "global", "asia-pacific", "southeast-asia", "europe", "americas", "north-america" ], "example": "global" }, "locations": { "type": "array", "description": "Custom location selectors. Provide exactly one of preset or locations.", "example": [ { "continent": "AS" }, { "country": "DE" }, { "magic": "berlin" } ], "items": {} } }, "required": [ "target" ] } ] } } } }, "responses": { "200": { "description": "Ping result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability or no active API plan", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:ping" } }, "\/tools\/ping\/batch": { "post": { "operationId": "tool.pingBatch", "description": "Runs multi-location ping checks for up to 10 IP targets and returns inline summary plus per-location detail for each target.\n\n**Required ability:** `tool:ping`", "summary": "Run a batch multi-location ping", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/PingBatchRequest" }, { "type": "object", "properties": { "targets": { "type": "array", "description": "Array of IP addresses to ping. Maximum 10 entries.", "example": [ "1.1.1.1", "8.8.8.8" ], "items": {} }, "packets": { "type": [ "integer", "null" ], "description": "Number of packets per probe. Allowed values: 1 to 10.", "example": 3, "minimum": 1, "maximum": 10 }, "limit": { "type": [ "integer", "null" ], "description": "Maximum probes per location selector. Allowed values: 1 to 5.", "example": 5, "minimum": 1, "maximum": 5 }, "preset": { "type": [ "string", "null" ], "description": "Named location preset. Provide exactly one of preset or locations.", "enum": [ "global", "asia-pacific", "southeast-asia", "europe", "americas", "north-america" ], "example": "global" }, "locations": { "type": "array", "description": "Custom location selectors. Provide exactly one of preset or locations.", "example": [ { "country": "ID" }, { "country": "SG" } ], "items": {} } }, "required": [ "targets" ] } ] } } } }, "responses": { "200": { "description": "Batch ping result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability or no active API plan", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:ping" } }, "\/tools\/email-validation": { "post": { "operationId": "tool.emailValidation", "description": "Validates up to 100 email addresses per request using shared Email Validation units across API and website.\n\n**Required ability:** `tool:email-validation`", "summary": "Validate email addresses", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/EmailValidationRequest" }, { "type": "object", "properties": { "emails": { "type": "array", "description": "Array of email addresses to validate. Maximum 100 entries per request.", "example": [ "alice@example.com", "bob@example.com" ], "items": {} } }, "required": [ "emails" ] } ] } } } }, "responses": { "200": { "description": "Email validation result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability or no active API plan", "content": { "application\/json": { "schema": { "type": "string" } } } }, "429": { "description": "Quota or concurrency exceeded", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:email-validation" } }, "\/tools\/email-deliverability-checker": { "post": { "operationId": "tool.emailDeliverabilityChecker", "description": "Analyzes SPF, DKIM, DMARC, and MX records for a domain and returns the same deliverability report shape used by the website tool.\n\n**Required ability:** `tool:email-deliverability-checker`", "summary": "Run the Email Deliverability Checker", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/EmailDeliverabilityCheckRequest" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name to inspect.", "example": "example.com", "maxLength": 255 } }, "required": [ "domain" ] } ] } } } }, "responses": { "200": { "description": "Email deliverability report", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability or no active API plan", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:email-deliverability-checker" } }, "\/tools\/blacklist-checker": { "post": { "operationId": "tool.blacklistChecker", "description": "Checks a single IP address or domain with target, or a batch with targets, against the existing blacklist provider set. Quick mode is enabled by default and batch requests support up to 10 targets.\n\n**Required ability:** `tool:blacklist-checker`", "summary": "Run the Blacklist Checker", "tags": [ "Tools" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/BlacklistCheckerRequest" }, { "type": "object", "properties": { "target": { "type": [ "string", "null" ], "description": "Single IP address or domain to inspect.", "example": "8.8.8.8", "maxLength": 255 }, "targets": { "type": "array", "description": "Batch of IP addresses or domains to inspect. Maximum 10 entries.", "example": [ "1.1.1.1", "example.com" ], "items": {} }, "quick_mode": { "type": "boolean", "description": "Whether to use the quick provider set instead of the full provider set.", "example": true } } } ] } } } }, "responses": { "200": { "description": "Blacklist checker result", "content": { "application\/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Missing required ability or no active API plan", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "x-required-ability": "tool:blacklist-checker" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Use a VPSMetrics API key in the Authorization header: Bearer . Create API keys from the authenticated \/account\/api-keys page.", "scheme": "bearer", "bearerFormat": "Bearer token" } }, "schemas": { "BlacklistCheckerRequest": { "type": "object", "properties": { "target": { "type": [ "string", "null" ], "maxLength": 255 }, "quick_mode": { "type": [ "boolean", "null" ] }, "targets": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 }, "minItems": 1, "maxItems": 10 } }, "title": "BlacklistCheckerRequest" }, "CrontabPreviewRequest": { "type": "object", "properties": { "expression": { "type": "string", "maxLength": 255 }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ], "enum": [ "en", "id" ] } }, "required": [ "expression" ], "title": "CrontabPreviewRequest" }, "CsvToJsonRequest": { "type": "object", "properties": { "csv": { "type": "string", "maxLength": 5000000 }, "delimiter": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1 }, "has_header": { "type": [ "boolean", "null" ] } }, "required": [ "csv" ], "title": "CsvToJsonRequest" }, "DmarcLookupRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 } }, "required": [ "domain" ], "title": "DmarcLookupRequest" }, "DnsLookupRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 }, "scope": { "type": [ "string", "null" ], "enum": [ "full", "core" ] } }, "required": [ "domain" ], "title": "DnsLookupRequest" }, "DnsPropagationCheckRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 }, "record_type": { "type": [ "string", "null" ], "enum": [ "A", "AAAA", "MX", "NS", "TXT", "CNAME", "SOA", "CAA", "SRV", "PTR" ] }, "mode": { "type": [ "string", "null" ], "enum": [ "fast", "reliable", "comprehensive", "all" ] } }, "required": [ "domain" ], "title": "DnsPropagationCheckRequest" }, "EmailDeliverabilityCheckRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 } }, "required": [ "domain" ], "title": "EmailDeliverabilityCheckRequest" }, "EmailValidationRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 255 }, "minItems": 1, "maxItems": 100 } }, "required": [ "emails" ], "title": "EmailValidationRequest" }, "PingBatchRequest": { "type": "object", "properties": { "packets": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "preset": { "type": [ "string", "null" ], "enum": [ "global", "asia-pacific", "southeast-asia", "europe", "americas", "north-america" ] }, "targets": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10 }, "locations": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "continent": { "type": [ "string", "null" ], "enum": [ "AF", "AS", "EU", "NA", "SA", "OC" ] }, "country": { "type": [ "string", "null" ], "enum": [ "ID", "SG", "MY", "TH", "PH", "VN", "JP", "KR", "AU", "IN", "US", "CA", "GB", "DE", "FR", "NL", "IT", "ES", "BR", "AR" ] }, "magic": { "type": [ "string", "null" ], "maxLength": 100 } }, "required": [ "continent", "country", "magic" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "targets" ], "title": "PingBatchRequest" }, "PingRequest": { "type": "object", "properties": { "target": { "type": "string", "maxLength": 255 }, "packets": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "preset": { "type": [ "string", "null" ], "enum": [ "global", "asia-pacific", "southeast-asia", "europe", "americas", "north-america" ] }, "locations": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "continent": { "type": [ "string", "null" ], "enum": [ "AF", "AS", "EU", "NA", "SA", "OC" ] }, "country": { "type": [ "string", "null" ], "enum": [ "ID", "SG", "MY", "TH", "PH", "VN", "JP", "KR", "AU", "IN", "US", "CA", "GB", "DE", "FR", "NL", "IT", "ES", "BR", "AR" ] }, "magic": { "type": [ "string", "null" ], "maxLength": 100 } }, "required": [ "continent", "country", "magic" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "target" ], "title": "PingRequest" }, "SpfLookupRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 } }, "required": [ "domain" ], "title": "SpfLookupRequest" }, "UptimeCalculatorRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "uptime", "reverse" ] }, "uptime": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "yearly", "custom" ] }, "custom_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650 }, "downtime_amount": { "type": [ "number", "null" ], "minimum": 0 }, "downtime_unit": { "type": "string", "enum": [ "seconds", "minutes", "hours" ] } }, "required": [ "mode", "period", "downtime_unit" ], "title": "UptimeCalculatorRequest" }, "WhatIsMyIpLookupRequest": { "type": "object", "properties": { "ip": { "type": [ "string", "null" ] }, "include_reputation": { "type": [ "boolean", "null" ] } }, "title": "WhatIsMyIpLookupRequest" }, "WhoisLookupRequest": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 }, "detail": { "type": [ "boolean", "null" ] } }, "required": [ "domain" ], "title": "WhoisLookupRequest" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }