{ "openapi": "3.1.1", "info": { "title": "Ops.Tools API Reference", "version": "1.0.0", "description": "Use the Ops.Tools API to add network, domain, and HTTP intelligence to your product or workflow.\n\nThe public API covers IP lookups, DNS records, WHOIS data, SSL certificate checks, HTTP header analysis, port scans, API key management, and usage reporting.\n\nAuthenticate each request with your API key by sending `x-api-key: YOUR_API_KEY` as a header. Query-string authentication is also supported for tools that cannot set custom headers.\n\nFor plans, limits, and billing, visit [ops.tools/pricing](https://ops.tools/pricing). For help, contact support@ops.tools.\n\n## AI Agents (MCP)\n\nThis API is also available as a hosted [MCP](https://modelcontextprotocol.io) server for AI agents at `https://api.ops.tools/mcp` — Streamable HTTP (JSON-RPC 2.0), authenticated with the same `x-api-key` header. Every tool call costs 1 credit; `account_whoami` is free. See the [MCP integration guide](https://ops.tools/guides/mcp-server) and the server card at `https://ops.tools/.well-known/mcp/server-card.json`.", "contact": { "name": "Ops.Tools Support", "url": "https://ops.tools", "email": "support@ops.tools" }, "license": { "name": "Proprietary", "url": "https://ops.tools/terms-of-service" }, "termsOfService": "https://ops.tools/terms-of-service" }, "servers": [ { "url": "https://api.ops.tools", "description": "Production Server", "variables": {} } ], "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ], "tags": [ { "name": "IP Lookup", "description": "Locate an IP address and identify its network owner, ASN, and regional details." }, { "name": "DNS", "description": "Resolve DNS records for a domain or host across common record types." }, { "name": "WHOIS", "description": "Retrieve registration data for a domain, with optional parsed JSON output." }, { "name": "SSL", "description": "Check certificate validity, expiry, issuer, and TLS metadata for a hostname." }, { "name": "HTTP Analysis", "description": "Inspect redirects, headers, caching, and security posture for a URL." }, { "name": "Port Scanner", "description": "Check which TCP services are reachable on a domain or IP address." }, { "name": "API Keys", "description": "Create, update, list, and inspect API keys for your account." }, { "name": "Usage", "description": "Review request volume and export usage reports for your account." } ], "paths": { "/v1-create-api-key": { "post": { "tags": ["API Keys"], "summary": "Create an API key", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "description": "API key name, service access, and enabled state." }, "responses": { "200": { "description": "The created API key, including the key value returned at creation time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "createApiKey", "description": "Create a new API key for your account. Use services to limit which Ops.Tools API products the key can call.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-delete-api-key": { "post": { "tags": ["API Keys"], "summary": "Delete an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyRequest" } } }, "description": "Identifier of the API key to delete." }, "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyResult" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "deleteApiKey", "description": "Permanently delete an API key owned by your account.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-get-api-key-details": { "post": { "tags": ["API Keys"], "summary": "Get API key details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiKeyRequest" } } }, "description": "Identifier of the API key to retrieve." }, "responses": { "200": { "description": "API key details, or null when no matching key is found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetails" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "getApiKey", "description": "Retrieve the settings and status for one API key owned by your account.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-list-api-keys": { "post": { "tags": ["API Keys"], "summary": "List API keys", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysRequest" } } }, "description": "No fields are required for this request." }, "responses": { "200": { "description": "List of API keys for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "listApiKeys", "description": "List the API keys available to your account.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-update-api-key": { "post": { "tags": ["API Keys"], "summary": "Update an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } }, "description": "Identifier of the API key plus the fields to update." }, "responses": { "200": { "description": "Updated API key details, or null when no matching key is found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedApiKey" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "updateApiKey", "description": "Change an API key name, environment, service access, or enabled state.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-who-am-i": { "get": { "tags": ["API Keys"], "summary": "Inspect the current API key", "responses": { "200": { "description": "Authenticated account and request context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentApiKeyContext" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "getCurrentApiKeyContext", "description": "Return account and request context for the API key used on the request.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-download-api-usage": { "get": { "tags": ["Usage"], "summary": "Export API usage", "parameters": [ { "schema": { "type": "string", "description": "Start date for the usage window, inclusive. Use ISO date format.", "example": "2026-03-01" }, "required": false, "name": "from", "in": "query", "description": "Start date for the usage window, inclusive. Use ISO date format." }, { "schema": { "type": "string", "description": "End date for the usage window, inclusive. Use ISO date format.", "example": "2026-03-31" }, "required": false, "name": "to", "in": "query", "description": "End date for the usage window, inclusive. Use ISO date format." }, { "schema": { "type": "string", "description": "Optional Ops.Tools service key to filter usage rows.", "example": "dns-lookup" }, "required": false, "name": "service", "in": "query", "description": "Optional Ops.Tools service key to filter usage rows." } ], "responses": { "200": { "description": "Download URL and file metadata for the usage export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageExport" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "createUsageExport", "description": "Create a downloadable usage export for a date range and optional service filter.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-get-api-usage": { "get": { "tags": ["Usage"], "summary": "List API usage", "parameters": [ { "schema": { "type": "string", "description": "Start date for the usage window, inclusive. Use ISO date format.", "example": "2026-03-01" }, "required": false, "name": "from", "in": "query", "description": "Start date for the usage window, inclusive. Use ISO date format." }, { "schema": { "type": "string", "description": "End date for the usage window, inclusive. Use ISO date format.", "example": "2026-03-31" }, "required": false, "name": "to", "in": "query", "description": "End date for the usage window, inclusive. Use ISO date format." }, { "schema": { "type": "string", "description": "Optional Ops.Tools service key to filter usage rows.", "example": "dns-lookup" }, "required": false, "name": "service", "in": "query", "description": "Optional Ops.Tools service key to filter usage rows." } ], "responses": { "200": { "description": "Daily usage rows for the selected filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "listUsage", "description": "Return daily usage totals for your account, optionally filtered by date range and service.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-get-ip-details": { "get": { "operationId": "getIpDetails", "tags": ["IP Lookup"], "summary": "Look up IP details", "description": "Resolve location, ASN, organization, and optional performance details for an IP address.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ], "parameters": [ { "schema": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ], "description": "IP address to inspect. When omitted, Ops.Tools uses the caller IP address.", "example": "8.8.8.8" }, "required": false, "description": "IP address to inspect. When omitted, Ops.Tools uses the caller IP address.", "name": "ip", "in": "query" }, { "schema": { "type": "string", "enum": ["maxmind", "geojs"], "description": "Optional provider override. Most customers can omit this.", "example": "maxmind" }, "required": false, "description": "Optional provider override. Most customers can omit this.", "name": "provider", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["0", "1", "true", "false"] } ], "default": false, "description": "Set to true to bypass cached results and fetch fresh data.", "example": false }, "required": false, "description": "Set to true to bypass cached results and fetch fresh data.", "name": "skipCache", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["0", "1", "true", "false"] } ], "default": false, "description": "Set to true to include timing details in the response.", "example": false }, "required": false, "description": "Set to true to include timing details in the response.", "name": "getPerformanceData", "in": "query" } ], "responses": { "200": { "description": "IP location and network ownership details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpDetails" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } } } }, "/v1-dns-lookup": { "get": { "tags": ["DNS"], "summary": "Look up DNS records", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Domain or hostname to resolve.", "example": "example.com" }, "required": true, "name": "address", "in": "query", "description": "Domain or hostname to resolve." }, { "schema": { "type": "string", "enum": ["A", "AAAA", "CNAME", "MX", "NAPTR", "NS", "PTR", "SOA", "SRV", "TXT", "ANY"], "default": "A", "description": "DNS record type to resolve.", "example": "A" }, "required": false, "name": "type", "in": "query", "description": "DNS record type to resolve." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to bypass cached results and fetch fresh data.", "example": false }, "required": false, "name": "skipCache", "in": "query", "description": "Set to true to bypass cached results and fetch fresh data." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to include timing details in the response.", "example": false }, "required": false, "name": "getPerformanceData", "in": "query", "description": "Set to true to include timing details in the response." }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional cache lifetime override in seconds.", "example": 3600 }, "required": false, "name": "cacheTimeSeconds", "in": "query", "description": "Optional cache lifetime override in seconds." } ], "responses": { "200": { "description": "DNS records and optional lookup timing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSLookupResult" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "lookupDnsRecords", "description": "Resolve DNS records for a domain or hostname. Choose a record type such as A, AAAA, MX, TXT, NS, CNAME, or ANY.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-whois-data": { "get": { "tags": ["WHOIS"], "summary": "Look up WHOIS data", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Domain name to inspect.", "example": "example.com" }, "required": true, "name": "domain", "in": "query", "description": "Domain name to inspect." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to bypass cached WHOIS data.", "example": false }, "required": false, "name": "noCache", "in": "query", "description": "Set to true to bypass cached WHOIS data." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to include parsed WHOIS fields when available.", "example": true }, "required": false, "name": "parseWhoisToJson", "in": "query", "description": "Set to true to include parsed WHOIS fields when available." }, { "schema": { "type": "string", "enum": ["iana", "shell"], "description": "Optional provider override. Most customers can omit this." }, "required": false, "name": "provider", "in": "query", "description": "Optional provider override. Most customers can omit this." }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional cache lifetime override in seconds.", "example": 3600 }, "required": false, "name": "cacheTimeSeconds", "in": "query", "description": "Optional cache lifetime override in seconds." } ], "responses": { "200": { "description": "Raw WHOIS text and optional parsed registration data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WHOISLookupResult" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "lookupWhoisData", "description": "Retrieve raw WHOIS registration data for a domain, with optional parsed JSON fields.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-ssl-checker": { "get": { "tags": ["SSL"], "summary": "Check an SSL certificate", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/i", "description": "Domain name to inspect.", "example": "example.com" }, "required": true, "name": "domain", "in": "query", "description": "Domain name to inspect." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "TLS port to connect to.", "example": 443 }, "required": false, "name": "port", "in": "query", "description": "TLS port to connect to." }, { "schema": { "type": "string", "enum": ["ssl-checker", "certificate"], "description": "Optional provider override. Most customers can omit this." }, "required": false, "name": "provider", "in": "query", "description": "Optional provider override. Most customers can omit this." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to bypass cached results and fetch fresh data.", "example": false }, "required": false, "name": "skipCache", "in": "query", "description": "Set to true to bypass cached results and fetch fresh data." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to include timing details in the response.", "example": false }, "required": false, "name": "getPerformanceData", "in": "query", "description": "Set to true to include timing details in the response." } ], "responses": { "200": { "description": "SSL certificate and TLS connection details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSLCertificateCheck" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "checkSslCertificate", "description": "Inspect certificate validity, expiry, issuer, subject names, TLS protocol, and chain details for a domain.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-analyze-http": { "get": { "tags": ["HTTP Analysis"], "summary": "Analyze an HTTP endpoint", "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "Fully qualified HTTP or HTTPS URL to analyze.", "example": "https://example.com" }, "required": true, "name": "url", "in": "query", "description": "Fully qualified HTTP or HTTPS URL to analyze." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": true, "description": "Follow redirects before returning the final response analysis.", "example": true }, "required": false, "name": "followRedirects", "in": "query", "description": "Follow redirects before returning the final response analysis." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to bypass cached results and fetch fresh data.", "example": false }, "required": false, "name": "skipCache", "in": "query", "description": "Set to true to bypass cached results and fetch fresh data." }, { "schema": { "type": "integer", "minimum": 1000, "maximum": 60000, "description": "Request timeout in milliseconds.", "example": 5000 }, "required": false, "name": "timeout", "in": "query", "description": "Request timeout in milliseconds." } ], "responses": { "200": { "description": "HTTP response metadata, headers, redirects, and analysis results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpAnalysisResult" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "analyzeHttpEndpoint", "description": "Inspect a URL for redirects, headers, security recommendations, caching, and response metadata.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } }, "/v1-port-scanner": { "get": { "tags": ["Port Scanner"], "summary": "Scan ports", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}|(\\d{1,3}\\.){3}\\d{1,3}$", "description": "Domain name or IP address to scan.", "example": "example.com" }, "required": true, "name": "target", "in": "query", "description": "Domain name or IP address to scan." }, { "schema": { "type": "string", "description": "Comma-separated list or range of ports to scan.", "example": "22,80,443" }, "required": false, "name": "ports", "in": "query", "description": "Comma-separated list or range of ports to scan." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Set to true to bypass cached results and fetch fresh data.", "example": false }, "required": false, "name": "skipCache", "in": "query", "description": "Set to true to bypass cached results and fetch fresh data." }, { "schema": { "type": "integer", "minimum": 500, "maximum": 30000, "default": 2500, "description": "Request timeout in milliseconds.", "example": 5000 }, "required": false, "name": "timeout", "in": "query", "description": "Request timeout in milliseconds." } ], "responses": { "200": { "description": "Port states, detected services, and scan summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortScanResult" } } } }, "400": { "description": "The request is missing required data or contains an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "A valid API key is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Your account needs credits or an active plan to complete this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "403": { "description": "The API key does not have access to this resource or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "The request exceeded the rate limit for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" } } } }, "500": { "description": "Ops.Tools could not complete the request because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "operationId": "scanPorts", "description": "Check whether selected TCP ports are open, closed, or filtered on a domain or IP address.", "security": [ { "ApiKeyAuth": [] }, { "JwtTokenAuth": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key authentication. Create keys under Account → API keys. Keys are scoped to the product host. The API key may also be passed as the `x-api-key` query parameter." }, "JwtTokenAuth": { "type": "apiKey", "in": "header", "name": "x-jwt-token", "description": "JWT session-token authentication. When both an API key and a JWT are present, the API key takes precedence." } }, "schemas": { "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true } }, "additionalProperties": { "nullable": true }, "description": "Fields used to create an API key for your account.", "example": { "name": "Production DNS Monitor", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true }, "title": "Create API Key Request" }, "ApiKey": { "type": "object", "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" }, "apiKey": { "type": "string", "description": "API key value used to authenticate requests.", "example": "ops_live_xxxxxxxxxxxxxxxxxxxx" }, "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "environment": { "type": "string", "description": "Environment label for the key, such as production or staging.", "example": "production" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true }, "host": { "type": "string", "description": "Product host associated with this key.", "example": "ops.tools" }, "note": { "type": "string", "description": "Optional customer note for this key.", "example": "Production monitoring key" }, "meta": { "nullable": true, "description": "Additional request or account metadata when available.", "example": { "reqIpAddress": "203.0.113.10" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Creation time in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Last update time in ISO 8601 format." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "API key details returned after creation. Store the key value securely; it may only be shown once.", "title": "API Key", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "ops_live_xxxxxxxxxxxxxxxxxxxx", "name": "Production DNS Monitor", "environment": "production", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true, "host": "ops.tools", "note": "Production monitoring key", "meta": { "reqIpAddress": "203.0.113.10" }, "createdAt": "2026-03-01T12:00:00.000Z", "updatedAt": "2026-03-01T12:00:00.000Z" } }, "BadRequestError": { "type": "object", "properties": { "error": { "type": "string", "example": "VALIDATION_ERROR", "description": "Error code identifier" }, "message": { "type": "string", "example": "Invalid request parameters", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Bad Request Error", "description": "The request could not be processed because required or valid data was missing." }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "string", "example": "AUTHENTICATION_REQUIRED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Authentication token is required", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Unauthorized Error", "description": "The request did not include a valid API key." }, "PaymentRequiredError": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_REQUIRED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Insufficient credits", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Payment Required Error", "description": "The account needs credits or an active plan before the request can be completed." }, "ForbiddenError": { "type": "object", "properties": { "error": { "type": "string", "example": "ACCESS_DENIED", "description": "Error code identifier" }, "message": { "type": "string", "example": "You do not have permission to perform this action", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Forbidden Error", "description": "The API key is valid but cannot access the requested resource or action." }, "NotFoundError": { "type": "object", "properties": { "error": { "type": "string", "example": "NOT_FOUND", "description": "Error code identifier" }, "message": { "type": "string", "example": "The requested resource was not found", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Not Found Error", "description": "The requested resource was not found." }, "TooManyRequestsError": { "type": "object", "properties": { "error": { "type": "string", "example": "RATE_LIMIT_EXCEEDED", "description": "Error code identifier" }, "message": { "type": "string", "example": "Too many requests, please try again later", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Rate Limit Error", "description": "The account has sent too many requests in the current window." }, "InternalServerError": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_SERVER_ERROR", "description": "Error code identifier" }, "message": { "type": "string", "example": "An unexpected error occurred", "description": "Human-readable error message" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "default": [], "description": "Validation or structured error details." } }, "required": ["error", "message"], "title": "Server Error", "description": "Ops.Tools could not complete the request because of an unexpected server error." }, "DeleteApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "description": "Identifier of the API key to delete.", "title": "Delete API Key Request", "example": { "_id": "507f1f77bcf86cd799439011" } }, "DeleteApiKeyResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the requested action succeeded.", "example": true } }, "required": ["success"], "description": "Confirmation that the API key was deleted.", "title": "Delete API Key Result", "example": { "success": true } }, "GetApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "description": "Identifier of the API key to retrieve.", "example": { "_id": "507f1f77bcf86cd799439011" }, "title": "Get API Key Request" }, "ApiKeyDetails": { "type": "object", "nullable": true, "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" }, "apiKey": { "type": "string", "description": "API key value used to authenticate requests.", "example": "ops_live_xxxxxxxxxxxxxxxxxxxx" }, "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "environment": { "type": "string", "description": "Environment label for the key, such as production or staging.", "example": "production" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true }, "host": { "type": "string", "description": "Product host associated with this key.", "example": "ops.tools" }, "note": { "type": "string", "description": "Optional customer note for this key.", "example": "Production monitoring key" }, "meta": { "nullable": true, "description": "Additional request or account metadata when available.", "example": { "reqIpAddress": "203.0.113.10" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Creation time in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Last update time in ISO 8601 format." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "API key configuration and status, or null when no matching key is found.", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "ops_live_xxxxxxxxxxxxxxxxxxxx", "name": "Production DNS Monitor", "environment": "production", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true, "host": "ops.tools", "note": "Production monitoring key", "meta": { "reqIpAddress": "203.0.113.10" }, "createdAt": "2026-03-01T12:00:00.000Z", "updatedAt": "2026-03-01T12:00:00.000Z" }, "title": "API Key Details" }, "ListApiKeysRequest": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "description": "Empty request body used to list your API keys.", "title": "List API Keys Request", "example": {} }, "ApiKeyList": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeySummary" } } }, "required": ["list"], "description": "API keys available to your account.", "title": "API Key List", "example": { "list": [ { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "ops_live_xxxxxxxxxxxxxxxxxxxx", "name": "Production DNS Monitor", "environment": "production", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true, "host": "ops.tools", "note": "Production monitoring key", "meta": { "reqIpAddress": "203.0.113.10" }, "createdAt": "2026-03-01T12:00:00.000Z", "updatedAt": "2026-03-01T12:00:00.000Z" } ] } }, "UpdateApiKeyRequest": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "maxLength": 255, "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "environment": { "type": "string", "description": "Environment label for the key, such as production or staging.", "example": "production" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true } }, "required": ["_id"], "additionalProperties": { "nullable": true }, "description": "Fields that can be changed for an existing API key.", "title": "Update API Key Request", "example": { "_id": "507f1f77bcf86cd799439011", "name": "Production Network Checks", "environment": "production", "services": ["ip-lookup", "dns-lookup", "port-scanner"], "isEnabled": true } }, "UpdatedApiKey": { "type": "object", "nullable": true, "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" }, "apiKey": { "type": "string", "description": "API key value used to authenticate requests.", "example": "ops_live_xxxxxxxxxxxxxxxxxxxx" }, "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "environment": { "type": "string", "description": "Environment label for the key, such as production or staging.", "example": "production" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true }, "host": { "type": "string", "description": "Product host associated with this key.", "example": "ops.tools" }, "note": { "type": "string", "description": "Optional customer note for this key.", "example": "Production monitoring key" }, "meta": { "nullable": true, "description": "Additional request or account metadata when available.", "example": { "reqIpAddress": "203.0.113.10" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Creation time in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Last update time in ISO 8601 format." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "Updated API key configuration, or null when no matching key is found.", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "ops_live_xxxxxxxxxxxxxxxxxxxx", "name": "Production DNS Monitor", "environment": "production", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true, "host": "ops.tools", "note": "Production monitoring key", "meta": { "reqIpAddress": "203.0.113.10" }, "createdAt": "2026-03-01T12:00:00.000Z", "updatedAt": "2026-03-01T12:00:00.000Z" }, "title": "Updated API Key" }, "CurrentApiKeyContext": { "type": "object", "properties": { "userId": { "type": "string", "nullable": true, "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" }, "email": { "type": "string", "nullable": true, "description": "Email address associated with the authenticated account when available.", "example": "developer@example.com" }, "username": { "type": "string", "nullable": true, "description": "Username associated with the authenticated account when available.", "example": "developer" }, "reqIpAddress": { "type": "string", "nullable": true, "description": "IP address seen by Ops.Tools for this request.", "example": "203.0.113.10" }, "reqIpCountry": { "type": "string", "nullable": true, "description": "Country inferred from the request IP when available.", "example": "US" }, "reqUserAgent": { "type": "string", "nullable": true, "description": "User agent sent with the request.", "example": "curl/8.0" } }, "description": "Account and request details for the API key used on the request.", "title": "Current API Key Context", "example": { "userId": "507f1f77bcf86cd799439012", "email": "developer@example.com", "username": "developer", "reqIpAddress": "203.0.113.10", "reqIpCountry": "US", "reqUserAgent": "curl/8.0" } }, "UsageExport": { "type": "object", "properties": { "url": { "type": "string", "description": "Original URL that was analyzed.", "example": "https://example.com" }, "filename": { "type": "string", "description": "Suggested filename for the export.", "example": "usage-2026-03.csv" }, "contentType": { "type": "string", "description": "MIME type of the export file.", "example": "text/csv" } }, "required": ["url", "filename", "contentType"], "description": "Download information for a generated usage report.", "title": "Usage Export", "example": { "url": "https://ops.tools/downloads/usage-2026-03.csv", "filename": "usage-2026-03.csv", "contentType": "text/csv" } }, "UsageSummary": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Usage date.", "example": "2026-03-12" }, "service": { "type": "string", "description": "Ops.Tools service key.", "example": "dns-lookup" }, "count": { "type": "number", "description": "Number of requests for the date and service.", "example": 14 }, "userId": { "type": "string", "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" } }, "required": ["date", "service", "count", "userId"] }, "description": "Daily request totals for your account.", "example": [ { "date": "2026-03-12", "service": "dns-lookup", "count": 14, "userId": "507f1f77bcf86cd799439011" } ], "title": "Usage Summary" }, "IpDetails": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8", "description": "IP address returned or inspected." }, "ptr": { "type": "string", "description": "Reverse DNS hostname when available.", "example": "dns.google" }, "city": { "$ref": "#/components/schemas/IpCity", "description": "City-level location details when available." }, "continentCode": { "type": "string", "description": "Two-letter continent code.", "example": "NA" }, "countryName": { "type": "string", "example": "United States", "description": "Country name." }, "countryCode": { "type": "string", "example": "US", "description": "Two-letter country code." }, "countryCode3": { "type": "string", "description": "Three-letter country code.", "example": "USA" }, "registeredCountryCode": { "type": "string", "description": "Country code for the registered network owner.", "example": "US" }, "asn": { "type": "number", "example": 15169, "description": "Autonomous system number." }, "aso": { "type": "string", "description": "Autonomous system organization.", "example": "Google LLC" }, "organization": { "type": "string", "example": "Google LLC", "description": "Network or organization name." }, "performance": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Timing details when requested." } }, "required": ["ip"], "title": "IP Details", "description": "Location and network ownership data for an IP address.", "example": { "ip": "8.8.8.8", "ptr": "dns.google", "countryName": "United States", "countryCode": "US", "asn": 15169, "organization": "Google LLC" } }, "HttpAnalysisResult": { "type": "object", "properties": { "url": { "type": "string", "description": "Original URL that was analyzed.", "example": "https://example.com" }, "finalUrl": { "type": "string", "description": "Final URL after following redirects.", "example": "https://www.example.com" }, "statusCode": { "type": "integer", "description": "HTTP response status code.", "example": 200 }, "timestamp": { "type": "string", "description": "Time the check was completed.", "example": "2026-03-01T12:00:00.000Z" }, "scanDurationMs": { "type": "number", "description": "Total scan duration in milliseconds.", "example": 742 }, "redirectChain": { "type": "array", "items": { "type": "string" }, "description": "Redirect URLs followed during analysis.", "example": ["https://www.example.com"] }, "rawHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Response headers returned by the endpoint." }, "analysis": { "type": "object", "properties": { "security": { "type": "object", "properties": { "grade": { "type": "string" }, "score": { "type": "number" }, "headers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "present": { "type": "boolean" }, "value": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning", "missing", "bad"] }, "recommendation": { "type": "string" } }, "required": ["present", "status"] } }, "missingHeaders": { "type": "array", "items": { "type": "string" } }, "issues": { "type": "array", "items": { "type": "string" } } }, "required": ["grade", "score", "headers", "missingHeaders", "issues"] }, "performance": { "type": "object", "properties": { "score": { "type": "number" }, "insights": { "type": "object", "properties": { "caching": { "type": "object", "properties": { "cacheControl": { "type": "object", "properties": { "present": { "type": "boolean" }, "value": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning", "missing", "bad"] }, "recommendation": { "type": "string" } }, "required": ["present", "status"] }, "expires": { "type": "object", "properties": { "present": { "type": "boolean" }, "value": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning", "missing", "bad"] }, "recommendation": { "type": "string" } }, "required": ["present", "status"] }, "etag": { "type": "object", "properties": { "present": { "type": "boolean" }, "status": { "type": "string", "enum": ["good", "warning", "missing"] } }, "required": ["present", "status"] } } }, "compression": { "type": "object", "properties": { "contentEncoding": { "type": "object", "properties": { "present": { "type": "boolean" }, "value": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning", "missing", "bad"] }, "recommendation": { "type": "string" } }, "required": ["present", "status"] } } }, "other": { "type": "object", "properties": { "keepAlive": { "type": "boolean" }, "protocol": { "type": "string" }, "recommendation": { "type": "string" } }, "required": ["keepAlive"] } }, "required": ["caching", "compression", "other"] }, "issues": { "type": "array", "items": { "type": "string" } } }, "required": ["score", "insights", "issues"], "description": "Timing details when requested." }, "general": { "type": "object", "properties": { "serverInfo": { "type": "object", "properties": { "server": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning"] }, "recommendation": { "type": "string" } }, "required": ["status"] }, "contentType": { "type": "string", "description": "MIME type of the export file.", "example": "text/csv" }, "cors": { "type": "object", "properties": { "allowOrigin": { "type": "string" }, "status": { "type": "string", "enum": ["good", "warning", "missing"] }, "recommendation": { "type": "string" } } }, "cookies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "secure": { "type": "boolean" }, "httponly": { "type": "boolean" }, "samesite": { "type": "string", "enum": ["Strict", "Lax", "None"] }, "status": { "type": "string", "enum": ["good", "warning"] } }, "required": ["name", "secure", "httponly", "status"] } } }, "required": ["serverInfo"] } }, "required": ["security", "performance", "general"], "description": "Security, performance, and header analysis." }, "summary": { "type": "object", "properties": { "overallGrade": { "type": "string" }, "keyRecommendations": { "type": "array", "items": { "type": "string" } } }, "required": ["overallGrade", "keyRecommendations"], "description": "Aggregate scan counts by port state." }, "cached": { "type": "boolean", "description": "Whether the result was served from cache.", "example": false }, "error": { "type": "string", "description": "Error code or details when a request could not be completed." } }, "required": [ "url", "finalUrl", "statusCode", "timestamp", "scanDurationMs", "rawHeaders", "analysis", "summary" ], "description": "Headers, redirects, status, security findings, caching details, and performance insights for a URL.", "example": { "url": "https://example.com", "finalUrl": "https://example.com", "statusCode": 200, "timestamp": "2026-01-01T00:00:00.000Z", "scanDurationMs": 210, "rawHeaders": { "content-type": "text/html; charset=UTF-8" }, "analysis": { "security": { "grade": "B", "score": 78, "headers": {}, "missingHeaders": [], "issues": [] }, "performance": { "score": 80, "insights": { "caching": {}, "compression": {}, "other": { "keepAlive": true } }, "issues": [] }, "general": { "serverInfo": { "status": "good" } } }, "summary": { "overallGrade": "B", "keyRecommendations": ["Add strict transport security header"] } }, "title": "HTTP Analysis Result" }, "PortScanResult": { "type": "object", "properties": { "target": { "type": "string", "description": "Domain name or IP address that was scanned.", "example": "example.com" }, "ip": { "type": "string", "description": "IP address returned or inspected.", "example": "8.8.8.8" }, "scanId": { "type": "string", "description": "Identifier for this scan result.", "example": "scan_01HX0000000000000000000000" }, "timestamp": { "type": "string", "description": "Time the check was completed.", "example": "2026-03-01T12:00:00.000Z" }, "scanDurationMs": { "type": "number", "description": "Total scan duration in milliseconds.", "example": 742 }, "ports": { "type": "array", "items": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "protocol": { "type": "string", "enum": ["tcp", "udp"] }, "state": { "type": "string", "enum": ["open", "closed", "filtered"] }, "service": { "type": "string", "description": "Ops.Tools service key.", "example": "dns-lookup" }, "banner": { "type": "string" }, "tlsVersion": { "type": "string" }, "cipherSuite": { "type": "string", "description": "Negotiated TLS cipher suite when available.", "example": "TLS_AES_256_GCM_SHA384" }, "certificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "expires": { "type": "string" }, "valid": { "type": "boolean" } }, "required": ["subject", "issuer", "expires", "valid"], "description": "Certificate details returned by the TLS endpoint." }, "responseTimeMs": { "type": "number" } }, "required": ["port", "protocol", "state", "service"] }, "description": "Results for each scanned port." }, "summary": { "type": "object", "properties": { "totalScanned": { "type": "integer", "minimum": 0 }, "open": { "type": "integer", "minimum": 0 }, "closed": { "type": "integer", "minimum": 0 }, "filtered": { "type": "integer", "minimum": 0 } }, "required": ["totalScanned", "open", "closed", "filtered"], "description": "Aggregate scan counts by port state." }, "cached": { "type": "boolean", "description": "Whether the result was served from cache.", "example": false }, "error": { "type": "string", "description": "Error code or details when a request could not be completed." } }, "required": ["target", "scanId", "timestamp", "scanDurationMs", "ports", "summary"], "description": "Reachability and service details for scanned ports on a target.", "title": "Port Scan Result" }, "ErrorDetail": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] } }, "additionalProperties": { "nullable": true }, "title": "Error Detail", "description": "Structured detail for a validation or request error." }, "ApiKeySummary": { "type": "object", "properties": { "_id": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Unique identifier for this API key.", "example": "507f1f77bcf86cd799439011" }, "userId": { "anyOf": [ { "type": "string", "format": "objectId", "example": "507f1f77bcf86cd799439011", "description": "Unique identifier." }, { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } ], "description": "Identifier for the account that owns this resource.", "example": "507f1f77bcf86cd799439012" }, "apiKey": { "type": "string", "description": "API key value used to authenticate requests.", "example": "ops_live_xxxxxxxxxxxxxxxxxxxx" }, "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "environment": { "type": "string", "description": "Environment label for the key, such as production or staging.", "example": "production" }, "services": { "type": "array", "items": { "type": "string" }, "description": "Ops.Tools services this key can access.", "example": ["dns-lookup", "ssl-checker"] }, "isEnabled": { "type": "boolean", "description": "Whether the key can currently authenticate requests.", "example": true }, "host": { "type": "string", "description": "Product host associated with this key.", "example": "ops.tools" }, "note": { "type": "string", "description": "Optional customer note for this key.", "example": "Production monitoring key" }, "meta": { "nullable": true, "description": "Additional request or account metadata when available.", "example": { "reqIpAddress": "203.0.113.10" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Creation time in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00.000Z", "description": "Last update time in ISO 8601 format." } }, "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"], "description": "Stored API key configuration shown in API key lists.", "title": "API Key Summary", "example": { "_id": "507f1f77bcf86cd799439011", "userId": "507f1f77bcf86cd799439012", "apiKey": "ops_live_xxxxxxxxxxxxxxxxxxxx", "name": "Production DNS Monitor", "environment": "production", "services": ["dns-lookup", "ssl-checker", "analyze-http"], "isEnabled": true, "host": "ops.tools", "note": "Production monitoring key", "meta": { "reqIpAddress": "203.0.113.10" }, "createdAt": "2026-03-01T12:00:00.000Z", "updatedAt": "2026-03-01T12:00:00.000Z" } }, "IpCity": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer-defined display name.", "example": "Production DNS Monitor" }, "region": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracyRadius": { "type": "number" }, "timeZone": { "type": "string" }, "areaCode": { "type": "string" } }, "required": ["latitude", "longitude", "accuracyRadius"], "title": "IP City", "description": "City-level location data when available for an IP address." }, "DNSLookupResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the requested action succeeded.", "example": true }, "address": { "type": "string", "description": "Domain or hostname that was resolved.", "example": "example.com" }, "type": { "type": "string", "enum": ["A", "AAAA", "CNAME", "MX", "NAPTR", "NS", "PTR", "SOA", "SRV", "TXT", "ANY"], "description": "DNS record type.", "example": "A" }, "records": { "nullable": true, "description": "Resolved DNS records for the requested type.", "example": ["93.184.216.34"] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code"], "description": "Error code or details when a request could not be completed." }, "performance": { "type": "object", "properties": { "totalTime": { "type": "number" }, "dnsLookupTime": { "type": "number" }, "cacheSkipped": { "type": "number" } }, "required": ["totalTime", "dnsLookupTime", "cacheSkipped"], "description": "Timing details when requested." } }, "required": ["success", "address", "type"], "description": "DNS records for the requested domain or hostname, with optional timing data.", "example": { "success": true, "address": "example.com", "type": "A", "records": ["93.184.216.34"] }, "title": "DNS Lookup Result" }, "WHOISLookupResult": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain that was inspected.", "example": "example.com" }, "whoisText": { "type": "string", "description": "Raw WHOIS response text.", "example": "Domain Name: EXAMPLE.COM" }, "whoisJson": { "nullable": true, "description": "Parsed WHOIS fields when requested and available.", "example": { "registrar": "Example Registrar" } }, "performance": { "nullable": true, "description": "Timing details when requested." } }, "required": ["domain", "whoisText"], "description": "Raw WHOIS text and optional parsed registration fields for a domain.", "example": { "domain": "example.com", "whoisText": "Domain Name: EXAMPLE.COM", "whoisJson": { "registrar": "Example Registrar" } }, "title": "WHOIS Lookup Result" }, "SSLCertificateCheck": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain that was inspected.", "example": "example.com" }, "port": { "type": "number" }, "certificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "daysRemaining": { "type": "number" }, "isValid": { "type": "boolean" }, "isExpired": { "type": "boolean" }, "isSelfSigned": { "type": "boolean" }, "serialNumber": { "type": "string" }, "fingerprint": { "type": "string" }, "version": { "type": "string" }, "keySize": { "type": "number" }, "signatureAlgorithm": { "type": "string" }, "subjectAltNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "subject", "issuer", "validFrom", "validTo", "daysRemaining", "isValid", "isExpired", "isSelfSigned" ], "description": "Certificate details returned by the TLS endpoint." }, "chain": { "type": "object", "properties": { "chainLength": { "type": "number" }, "isValidChain": { "type": "boolean" } }, "required": ["chainLength", "isValidChain"], "description": "Certificate chain summary." }, "protocols": { "type": "array", "items": { "type": "string" }, "description": "Supported or negotiated TLS protocol information.", "example": ["TLSv1.3"] }, "cipherSuite": { "type": "string", "description": "Negotiated TLS cipher suite when available.", "example": "TLS_AES_256_GCM_SHA384" }, "cached": { "type": "boolean", "description": "Whether the result was served from cache.", "example": false }, "provider": { "type": "string" }, "performance": { "type": "object", "properties": { "totalTime": { "type": "number" }, "fetchTime": { "type": "number" }, "cacheSkipped": { "type": "number" }, "isValid": { "type": "number" }, "daysRemaining": { "type": "number" } }, "required": ["totalTime", "fetchTime", "cacheSkipped", "isValid", "daysRemaining"], "description": "Timing details when requested." } }, "required": ["domain", "port", "certificate"], "description": "Certificate, chain, protocol, and expiry details for a domain.", "title": "SSL Certificate Check" } } } }