{ "openapi": "3.1.0", "info": { "title": "Lightning Tools API", "description": "Pay-per-call tools for AI agents. Buy credits with Bitcoin Lightning, spend them on tool calls. Every response includes X-Credits-Remaining so agents can track their balance.", "version": "1.0.0", "contact": { "url": "https://lightningapi.tools" } }, "servers": [ { "url": "https://api.lightningapi.tools", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from POST /api/v1/credits after paying a Lightning invoice. Format: sk_" } }, "headers": { "XCreditsRemaining": { "description": "Remaining credit balance after this request", "schema": { "type": "integer" } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } }, "PaymentRequired": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Insufficient credits" }, "required": { "type": "integer", "example": 3 } } } } } }, "ValidationError": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "details": { "type": "array", "items": {} } } } } } } } }, "paths": { "/": { "get": { "operationId": "discoveryRoot", "summary": "API discovery root", "description": "Returns a JSON discovery document with links to the OpenAPI spec, health check, and documentation.", "security": [], "tags": [ "Meta" ], "responses": { "200": { "description": "Discovery document", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "spec": { "type": "string", "example": "https://api.lightningapi.tools/openapi.json" }, "health": { "type": "string", "example": "https://api.lightningapi.tools/health" }, "docs": { "type": "string", "example": "https://lightningapi.tools" } } } } } } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns service health status.", "security": [], "tags": [ "Meta" ], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } } } } }, "/api/v1/credits": { "post": { "operationId": "purchaseCredits", "summary": "Buy credits", "description": "Creates a Lightning invoice. Pay the invoice, then call /api/v1/credits/verify to receive your API key.", "security": [], "tags": [ "Credits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "description": "Number of credits to purchase (1 credit = 1 sat)", "example": 1000 }, "email": { "type": "string", "format": "email", "description": "Optional. Associate an email with the account for recovery.", "example": "agent@example.com" }, "accountId": { "type": "string", "format": "uuid", "description": "Optional. Top up an existing account." } } } } } }, "responses": { "400": { "$ref": "#/components/responses/ValidationError" }, "402": { "description": "Lightning invoice created — pay the BOLT-11 invoice, then call /api/v1/credits/verify", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoice": { "type": "string", "description": "BOLT-11 Lightning invoice" }, "amount": { "type": "integer", "description": "Amount in satoshis" }, "accountId": { "type": "string", "format": "uuid" } } } } } } } } }, "/api/v1/credits/verify": { "post": { "operationId": "verifyPayment", "summary": "Verify payment and receive API key", "description": "After paying the Lightning invoice, call this endpoint to confirm payment and receive your API key.", "security": [], "tags": [ "Credits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoiceId", "quantity" ], "properties": { "invoiceId": { "type": "string", "description": "Invoice ID from POST /api/v1/credits" }, "quantity": { "type": "integer", "description": "Must match quantity from the original purchase request" } } } } } }, "responses": { "200": { "description": "Payment confirmed — API key returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "sk_abc123..." }, "credits": { "type": "integer" }, "accountId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_invoice" }, "message": { "type": "string", "example": "Invoice not found" } } }, { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_invoice" }, "message": { "type": "string", "example": "Quantity mismatch between request and invoice" } } } ] } } } }, "402": { "description": "Invoice not yet paid — poll again or wait for SSE event at GET /events/{invoiceId}" } } } }, "/api/v1/balance": { "get": { "operationId": "getBalance", "summary": "Get credit balance", "description": "Returns the current available and total credit balance for the authenticated account.", "tags": [ "Credits" ], "responses": { "200": { "description": "Current credit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/events/{invoiceId}": { "get": { "operationId": "watchInvoicePayment", "summary": "Watch for invoice payment", "description": "Server-Sent Events stream. Sends a \"paid\" event when the Lightning invoice is paid, \"timeout\" after 10 minutes, or \"ping\" heartbeat comments every 30s. Connect immediately after creating an invoice.", "security": [], "tags": [ "Credits" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream — events: paid, timeout", "content": { "text/event-stream": {} } } } } }, "/email-validator": { "post": { "operationId": "validateEmail", "summary": "Validate an email address", "description": "Validates an email address and returns a comprehensive quality signal including syntax, DNS, MX, disposable check, role account detection, free provider detection, domain age, and a 0-1 quality score. Cost: 2 credits per call. Idempotency-Key header is recommended — use the same key to safely retry without being charged twice.", "x-price": 2, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@acmecorp.com" } } } } } }, "responses": { "200": { "description": "Validation result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "valid": { "type": "boolean", "description": "true only if syntax, DNS, and MX all pass" }, "syntax": { "type": "boolean" }, "dns": { "type": "boolean" }, "mx": { "type": "boolean" }, "role_account": { "type": "boolean", "description": "Local part is a role address (admin, support, sales…)" }, "disposable": { "type": "boolean", "description": "Domain is a known throwaway provider" }, "free_provider": { "type": "boolean", "description": "Domain is a known free email provider" }, "domain_type": { "type": "string", "enum": [ "disposable", "free", "corporate", "unknown" ] }, "domain_age_days": { "type": "integer", "nullable": true, "description": "Days since domain registration. null if WHOIS unavailable." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "0-1 quality signal. 1 = strong signal of a real address." } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/calculator": { "post": { "operationId": "calculate", "summary": "Evaluate a mathematical expression", "description": "Evaluates arithmetic, algebra, trigonometry, logarithms, unit conversions, and natural language math. Accepts mathjs syntax (e.g. 'sqrt(144)', 'log(100, 10)', '1 mile to km') or plain English (e.g. 'square root of 144', '15% of 340', '100 celsius to fahrenheit'). Cost: 1 credit per call. Idempotency-Key header is recommended — use the same key to safely retry without being charged twice.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expression" ], "properties": { "expression": { "type": "string", "description": "A mathematical expression in mathjs syntax or plain English.", "example": "sqrt(144)" } } } } } }, "responses": { "200": { "description": "Calculation result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The computed value (number, boolean, string, or array depending on the expression)" }, "expression": { "type": "string", "description": "The expression that was evaluated. For natural language input this shows the normalised mathjs form." } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/qr-code": { "post": { "operationId": "generateQrCode", "summary": "Generate a QR code", "description": "Generates a QR code as a base64 PNG string or SVG string. Cost: 1 credit per call. Idempotency-Key header is recommended — use the same key to safely retry without being charged twice.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Content to encode in the QR code", "example": "https://example.com" }, "format": { "type": "string", "enum": [ "png", "svg" ], "default": "png", "description": "png returns a raw base64 string. svg returns an SVG string." }, "size": { "type": "integer", "minimum": 64, "maximum": 1024, "default": 256, "description": "Width/height in pixels (PNG only)" }, "errorCorrectionLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ], "default": "M", "description": "L=7%, M=15%, Q=25%, H=30% data recovery capability" } } } } } }, "responses": { "200": { "description": "QR code generated", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "format": { "type": "string" }, "data": { "type": "string", "description": "Raw base64 PNG or SVG string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/extract-text": { "post": { "operationId": "extractText", "summary": "Extract text from a URL", "description": "Fetches a URL and extracts clean readable text using Mozilla Readability. Returns title, plain text, clean HTML, excerpt, byline, and word count. Text is cleaned of excess whitespace and HTML artefacts. All fields except url are nullable. Cost: 2 credits per call.", "x-price": 2, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to fetch and extract content from.", "example": "https://en.wikipedia.org/wiki/Node.js" } } } } } }, "responses": { "200": { "description": "Extracted content. All fields except url are nullable — Readability may not extract every field from every page.", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "nullable": true }, "byline": { "type": "string", "nullable": true, "description": "Author name or byline if detected" }, "excerpt": { "type": "string", "nullable": true, "description": "Short excerpt or lede" }, "html": { "type": "string", "nullable": true, "description": "Clean article HTML with boilerplate stripped" }, "text": { "type": "string", "nullable": true, "description": "Plain text body" }, "wordCount": { "type": "integer", "nullable": true, "description": "Word count of plain text body" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/phone-validator": { "post": { "operationId": "validatePhone", "summary": "Validate a phone number", "description": "Validates and parses a phone number using libphonenumber-js. Returns country, type (MOBILE/FIXED_LINE/VOIP/etc.), and formatted variants. Invalid numbers return valid:false with HTTP 200 — credits are still charged. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Phone number to validate. E.164 format preferred (e.g. +353861234567). National format accepted with country hint.", "example": "+353861234567" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code hint for parsing national-format numbers (e.g. IE, US, GB)", "example": "IE" } } } } } }, "responses": { "200": { "description": "Validation result. valid:false means the number is not a real number — this is not an error, credits are charged.", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "valid": { "type": "boolean", "enum": [ true ] }, "phone": { "type": "string" }, "country": { "type": "string", "example": "IE" }, "countryCallingCode": { "type": "string", "example": "353" }, "type": { "type": "string", "example": "MOBILE", "description": "MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, TOLL_FREE, PREMIUM_RATE, VOIP, UNKNOWN, etc." }, "formatted": { "type": "object", "properties": { "national": { "type": "string", "example": "086 123 4567" }, "international": { "type": "string", "example": "+353 86 123 4567" }, "e164": { "type": "string", "example": "+353861234567" } } } } }, { "type": "object", "properties": { "valid": { "type": "boolean", "enum": [ false ] }, "phone": { "type": "string" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/feels-like": { "post": { "operationId": "feelsLike", "summary": "Apparent temperature", "description": "Calculates the apparent (feels-like) temperature using heat index or wind chill. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "temp_c" ], "properties": { "temp_c": { "type": "number", "description": "Temperature in Celsius" }, "humidity_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Relative humidity percentage (0-100)" }, "wind_speed_kmh": { "type": "number", "description": "Wind speed in km/h" } } } } } }, "responses": { "200": { "description": "Apparent temperature result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "feels_like_c": { "type": "number" }, "condition": { "type": "string", "enum": [ "heat_index", "wind_chill", "actual" ] } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/sunrise-sunset": { "post": { "operationId": "sunriseSunset", "summary": "Solar times", "description": "Calculates sunrise, sunset, solar noon, and day length for a given location and date. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "lon", "date" ], "properties": { "lat": { "type": "number", "description": "Latitude" }, "lon": { "type": "number", "description": "Longitude" }, "date": { "type": "string", "description": "Date in YYYY-MM-DD format", "example": "2026-06-21" } } } } } }, "responses": { "200": { "description": "Solar times result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "sunrise_utc": { "type": "string", "nullable": true }, "sunset_utc": { "type": "string", "nullable": true }, "solar_noon_utc": { "type": "string" }, "day_length_hours": { "type": "number", "nullable": true }, "polar_day": { "type": "boolean" }, "polar_night": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/age-in-units": { "post": { "operationId": "ageInUnits", "summary": "Age calculator", "description": "Calculates age in multiple units from a birthdate. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthdate" ], "properties": { "birthdate": { "type": "string", "description": "Birthdate in YYYY-MM-DD format", "example": "1990-05-15" }, "reference_date": { "type": "string", "description": "Optional reference date in YYYY-MM-DD format. Defaults to today." } } } } } }, "responses": { "200": { "description": "Age in multiple units", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "years": { "type": "integer" }, "months": { "type": "integer" }, "weeks": { "type": "integer" }, "days": { "type": "integer" }, "hours": { "type": "integer" }, "heartbeats": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/loan-payoff": { "post": { "operationId": "loanPayoff", "summary": "Amortisation calculator", "description": "Calculates loan payoff schedule including months to payoff, total interest, and total paid. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "principal", "annual_rate_pct", "monthly_payment" ], "properties": { "principal": { "type": "number", "exclusiveMinimum": 0, "description": "Loan principal amount" }, "annual_rate_pct": { "type": "number", "minimum": 0, "description": "Annual interest rate as a percentage" }, "monthly_payment": { "type": "number", "exclusiveMinimum": 0, "description": "Monthly payment amount" } } } } } }, "responses": { "200": { "description": "Loan payoff result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "number" }, "months_to_payoff": { "type": "integer" }, "total_interest": { "type": "number" }, "total_paid": { "type": "number" }, "error": { "type": "string", "enum": [ "payment_too_low" ] }, "minimum_payment": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/compound-interest": { "post": { "operationId": "compoundInterest", "summary": "Compound interest calculator", "description": "Calculates compound interest with year-by-year breakdown. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "principal", "annual_rate_pct", "years", "compounds_per_year" ], "properties": { "principal": { "type": "number", "description": "Initial principal amount" }, "annual_rate_pct": { "type": "number", "description": "Annual interest rate as a percentage" }, "years": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of years" }, "compounds_per_year": { "type": "integer", "description": "Number of compounding periods per year" } } } } } }, "responses": { "200": { "description": "Compound interest result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "final_amount": { "type": "number" }, "total_interest": { "type": "number" }, "year_by_year": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "balance": { "type": "number" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/elo-rating": { "post": { "operationId": "eloRating", "summary": "Elo chess rating calculator", "description": "Calculates new Elo ratings after a match. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rating_a", "rating_b", "outcome" ], "properties": { "rating_a": { "type": "number", "description": "Current rating of player A" }, "rating_b": { "type": "number", "description": "Current rating of player B" }, "outcome": { "type": "string", "enum": [ "a_wins", "b_wins", "draw" ], "description": "Match outcome" }, "k_factor": { "type": "number", "default": 32, "description": "K-factor (default 32)" } } } } } }, "responses": { "200": { "description": "Updated Elo ratings", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_rating_a": { "type": "number" }, "new_rating_b": { "type": "number" }, "delta_a": { "type": "number" }, "delta_b": { "type": "number" }, "expected_score_a": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/password-entropy": { "post": { "operationId": "passwordEntropy", "summary": "Password strength analyser", "description": "Calculates password entropy and estimated crack time. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "minLength": 1, "description": "Password to analyse" } } } } } }, "responses": { "200": { "description": "Password entropy result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entropy_bits": { "type": "number" }, "strength": { "type": "string", "enum": [ "very_weak", "weak", "fair", "strong", "very_strong" ] }, "charset": { "type": "object", "properties": { "lowercase": { "type": "boolean" }, "uppercase": { "type": "boolean" }, "digits": { "type": "boolean" }, "symbols": { "type": "boolean" } } }, "crack_time_offline_fast_seconds": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/boiling-point": { "post": { "operationId": "boilingPoint", "summary": "Boiling point at altitude", "description": "Calculates the boiling point of water at a given altitude. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "altitude_m" ], "properties": { "altitude_m": { "type": "number", "minimum": 0, "maximum": 10000, "description": "Altitude in metres (0-10000)" } } } } } }, "responses": { "200": { "description": "Boiling point result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "boiling_point_c": { "type": "number" }, "boiling_point_f": { "type": "number" }, "cooking_note": { "type": "string", "nullable": true } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/horizon-distance": { "post": { "operationId": "horizonDistance", "summary": "Horizon distance calculator", "description": "Calculates the distance to the geometric and radio horizons from a given height. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "height_m" ], "properties": { "height_m": { "type": "number", "exclusiveMinimum": 0, "description": "Height in metres (positive)" } } } } } }, "responses": { "200": { "description": "Horizon distance result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "geometric_km": { "type": "number" }, "radio_km": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/speed-of-sound": { "post": { "operationId": "speedOfSound", "summary": "Speed of sound calculator", "description": "Calculates the speed of sound in a given medium at a given temperature. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "temp_c", "medium" ], "properties": { "temp_c": { "type": "number", "description": "Temperature in Celsius" }, "medium": { "type": "string", "enum": [ "air", "water", "steel", "concrete" ], "description": "Medium for sound propagation" } } } } } }, "responses": { "200": { "description": "Speed of sound result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "speed_ms": { "type": "number" }, "speed_kmh": { "type": "number" }, "mach_1_ms": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/circuits/resource-reality-check": { "post": { "operationId": "resourceRealityCheck", "summary": "Resource reality check", "description": "Checks whether a URL is reachable and gathers signals about DNS, HTTP, SSL, and content. Cost: 3 credits per call.", "x-price": 3, "tags": [ "Circuits" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL to check" } } } } } }, "responses": { "200": { "description": "Resource reality check result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reachable": { "type": "boolean" }, "signals": { "type": "object", "properties": { "dns_resolves": { "type": "boolean", "nullable": true }, "http_status": { "type": "integer", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "ssl_valid": { "type": "boolean", "nullable": true }, "ssl_days_remaining": { "type": "number", "nullable": true } } }, "flags": { "type": "array", "items": { "type": "string" } }, "anomaly_count": { "type": "integer" }, "signals_checked": { "type": "integer" }, "partial": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/circuits/scam-signal-check": { "post": { "operationId": "scamSignalCheck", "summary": "Scam signal check", "description": "Analyses domain age, MX configuration, email deliverability, and payment method for scam signals. Cost: 4 credits per call.", "x-price": 4, "tags": [ "Circuits" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "sender_email" ], "properties": { "domain": { "type": "string", "description": "Domain to check" }, "sender_email": { "type": "string", "format": "email", "description": "Sender email address" }, "payment_method": { "type": "string", "description": "Payment method mentioned (optional)" } } } } } }, "responses": { "200": { "description": "Scam signal check result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "object", "properties": { "domain_age_days": { "type": "integer", "nullable": true }, "mx_configured": { "type": "boolean", "nullable": true }, "email_deliverable": { "type": "boolean", "nullable": true }, "payment_method": { "type": "string", "nullable": true } } }, "flags": { "type": "array", "items": { "type": "string" } }, "anomaly_count": { "type": "integer" }, "signals_checked": { "type": "integer" }, "partial": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/circuits/data-freshness-check": { "post": { "operationId": "dataFreshnessCheck", "summary": "Data freshness check", "description": "Checks URL reachability, domain update recency, SSL validity, and content word count for data freshness signals. Cost: 5 credits per call.", "x-price": 5, "tags": [ "Circuits" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL to check" } } } } } }, "responses": { "200": { "description": "Data freshness check result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "object", "properties": { "url_reachable": { "type": "boolean", "nullable": true }, "domain_updated": { "type": "string", "nullable": true }, "ssl_days_remaining": { "type": "number", "nullable": true }, "ssl_valid_to": { "type": "string", "nullable": true }, "word_count": { "type": "integer", "nullable": true } } }, "flags": { "type": "array", "items": { "type": "string" } }, "anomaly_count": { "type": "integer" }, "signals_checked": { "type": "integer" }, "partial": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/today": { "post": { "operationId": "dateUtilsToday", "summary": "Get current date and time info", "description": "Returns the current date, day of week, UTC offset, DST status, working day status, week number, quarter, days until month/quarter end, next working day, and upcoming holidays. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "type": "string", "example": "Europe/Dublin", "description": "IANA timezone string. Default: UTC" }, "country": { "type": "string", "example": "IE", "description": "ISO 3166-1 alpha-2. Enables holiday data." } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-03-27" }, "day_of_week": { "type": "string", "example": "Friday" }, "timezone": { "type": "string", "example": "Europe/Dublin" }, "utc_offset": { "type": "string", "example": "+00:00" }, "is_dst": { "type": "boolean" }, "working_day": { "type": "boolean" }, "reason": { "type": "string", "description": "Reason if not a working day" }, "week_number": { "type": "integer" }, "quarter": { "type": "integer" }, "days_until_month_end": { "type": "integer" }, "days_until_quarter_end": { "type": "integer" }, "next_working_day": { "type": "string", "example": "2026-03-30" }, "upcoming_holidays": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "name": { "type": "string" } } }, "description": "Upcoming holidays in the next 7 days (only when country is provided)" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/convert-time": { "post": { "operationId": "dateUtilsConvertTime", "summary": "Convert datetime between timezones", "description": "Converts an ISO 8601 datetime from one IANA timezone to another, including UTC offset and DST info. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "datetime", "from_timezone", "to_timezone" ], "properties": { "datetime": { "type": "string", "example": "2026-03-15T14:30:00" }, "from_timezone": { "type": "string", "example": "America/New_York" }, "to_timezone": { "type": "string", "example": "Asia/Tokyo" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "original": { "type": "object", "properties": { "datetime": { "type": "string" }, "timezone": { "type": "string" }, "utc_offset": { "type": "string" }, "is_dst": { "type": "boolean" } } }, "converted": { "type": "object", "properties": { "datetime": { "type": "string" }, "timezone": { "type": "string" }, "utc_offset": { "type": "string" }, "is_dst": { "type": "boolean" } } }, "difference_minutes": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/is-working-day": { "post": { "operationId": "dateUtilsIsWorkingDay", "summary": "Check if a date is a working day", "description": "Returns whether a date is a working day for a given country, including holiday details if not. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "country" ], "properties": { "date": { "type": "string", "example": "2026-04-17" }, "country": { "type": "string", "example": "IE" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string" }, "country": { "type": "string" }, "working_day": { "type": "boolean" }, "reason": { "type": "string", "description": "Reason if not a working day" }, "holiday": { "type": "object", "properties": { "name": { "type": "string" }, "local_name": { "type": "string" } }, "description": "Holiday details if the date falls on a public holiday" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/next-working-day": { "post": { "operationId": "dateUtilsNextWorkingDay", "summary": "Find next or previous working day", "description": "Finds the next (or previous) working day after a given date, skipping weekends and public holidays. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "country" ], "properties": { "date": { "type": "string", "example": "2026-04-16" }, "country": { "type": "string", "example": "IE" }, "direction": { "type": "string", "enum": [ "forward", "backward" ], "default": "forward" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string" }, "direction": { "type": "string", "enum": [ "forward", "backward" ] }, "next_working_day": { "type": "string" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "reason": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/add-working-days": { "post": { "operationId": "dateUtilsAddWorkingDays", "summary": "Add working days to a date", "description": "Adds N working days to a date (negative = backward), skipping weekends and public holidays. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "days", "country" ], "properties": { "date": { "type": "string", "example": "2026-04-14" }, "days": { "type": "integer", "example": 5, "description": "Non-zero integer, -365 to 365" }, "country": { "type": "string", "example": "IE" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string" }, "days": { "type": "integer" }, "country": { "type": "string" }, "result_date": { "type": "string" }, "working_days_added": { "type": "integer" }, "calendar_days_elapsed": { "type": "integer" }, "skipped_holidays": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/count-working-days": { "post": { "operationId": "dateUtilsCountWorkingDays", "summary": "Count working days in a date range", "description": "Counts working days between start and end (inclusive), excluding weekends and public holidays. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start", "end", "country" ], "properties": { "start": { "type": "string", "example": "2026-04-01" }, "end": { "type": "string", "example": "2026-04-30" }, "country": { "type": "string", "example": "IE" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "country": { "type": "string" }, "working_days": { "type": "integer" }, "calendar_days": { "type": "integer" }, "weekends_excluded": { "type": "integer" }, "holidays_excluded": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/meeting-windows": { "post": { "operationId": "dateUtilsMeetingWindows", "summary": "Find days all countries are available", "description": "Returns working day availability for 2-5 countries over a date range (max 90 days), identifying days when all countries are simultaneously available. Cost: 2 credits.", "x-price": 2, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "countries", "from_date", "to_date" ], "properties": { "countries": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 5, "example": [ "IE", "US", "DE" ] }, "from_date": { "type": "string", "example": "2026-03-14" }, "to_date": { "type": "string", "example": "2026-03-21" } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string" }, "to_date": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "windows": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "day_of_week": { "type": "string" }, "available_in_all": { "type": "boolean" }, "availability": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "working_day": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/date-utils/timezone-overlap": { "post": { "operationId": "dateUtilsTimezoneOverlap", "summary": "Find overlapping working hours across timezones", "description": "Finds the UTC window where all specified timezones are simultaneously within working hours. Cost: 1 credit.", "x-price": 1, "tags": [ "Date Utils" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Recommended. Provide a stable UUID per logical request so retries don't double-charge." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "timezones" ], "properties": { "date": { "type": "string", "example": "2026-03-16" }, "timezones": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "example": [ "Europe/Dublin", "America/New_York" ] }, "working_hours": { "type": "object", "properties": { "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "17:00" } } } } } } } }, "responses": { "200": { "description": "Result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string" }, "working_hours": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "timezones": { "type": "array", "items": { "type": "string" } }, "overlap_minutes": { "type": "integer" }, "best_windows": { "type": "array", "items": { "type": "object", "properties": { "start_utc": { "type": "string" }, "end_utc": { "type": "string" }, "duration_minutes": { "type": "integer" }, "local_times": { "type": "array", "items": { "type": "object", "properties": { "timezone": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } } } } }, "local_working_hours": { "type": "array", "items": { "type": "object", "properties": { "timezone": { "type": "string" }, "start_utc": { "type": "string" }, "end_utc": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/domain-intelligence/dns": { "post": { "operationId": "domainDns", "summary": "DNS lookup for a domain", "description": "Returns A, AAAA, MX, TXT, NS records and derived signals: spf_present, dmarc_present, mx_count. Cost: 1 credit per call. Provide Idempotency-Key to retry safely.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per request. Retry with the same key without double-charging." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to look up", "example": "example.com" } } } } } }, "responses": { "200": { "description": "DNS records and derived signals", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "domain": { "type": "string" }, "a": { "type": "array", "items": { "type": "string" } }, "aaaa": { "type": "array", "items": { "type": "string" } }, "mx": { "type": "array", "items": { "type": "object", "properties": { "exchange": { "type": "string" }, "priority": { "type": "number" } } } }, "txt": { "type": "array", "items": { "type": "string" } }, "ns": { "type": "array", "items": { "type": "string" } }, "spf_present": { "type": "boolean" }, "dmarc_present": { "type": "boolean" }, "mx_count": { "type": "number" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "domain": { "type": "string" }, "error": { "type": "string", "example": "nxdomain" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/domain-intelligence/whois": { "post": { "operationId": "domainWhois", "summary": "WHOIS / RDAP lookup for a domain", "description": "Returns registrar, registration date, expiry date, domain age in days, and days until expiry. Uses RDAP with WHOIS fallback. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per request. Retry with the same key without double-charging." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to look up", "example": "example.com" } } } } } }, "responses": { "200": { "description": "WHOIS/RDAP result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "domain": { "type": "string" }, "registrar": { "type": "string", "nullable": true }, "created": { "type": "string", "format": "date", "nullable": true }, "expires": { "type": "string", "format": "date", "nullable": true }, "updated": { "type": "string", "format": "date", "nullable": true }, "age_days": { "type": "number", "nullable": true }, "expires_in_days": { "type": "number", "nullable": true }, "registrant_country": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "rdap", "whois" ] } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "domain": { "type": "string" }, "error": { "type": "string", "enum": [ "not_found", "timeout", "parse_error" ] } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/domain-intelligence/http": { "post": { "operationId": "domainHttp", "summary": "HTTP probe — status, redirects, content type, response time", "description": "Follows redirects (max 10), records the full chain, and returns final status code, content type, and response time in ms. Only http/https URLs to public hosts are accepted. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per request. Retry with the same key without double-charging." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL to probe. Must be http or https. Private/loopback IPs are rejected.", "example": "https://example.com" } } } } } }, "responses": { "200": { "description": "HTTP probe result", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "url": { "type": "string" }, "status_code": { "type": "number" }, "content_type": { "type": "string", "nullable": true }, "redirect_chain": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "number" } } } }, "response_time_ms": { "type": "number" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "url": { "type": "string" }, "error": { "type": "string", "example": "unreachable" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/domain-intelligence/ssl": { "post": { "operationId": "domainSsl", "summary": "TLS/SSL certificate inspection", "description": "Inspects the TLS certificate for a domain: validity, expiry date, days remaining, issuer, SANs, and hostname match. Cost: 1 credit per call.", "x-price": 1, "tags": [ "Tools" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique key per request. Retry with the same key without double-charging." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain to inspect. Do not include https://.", "example": "example.com" } } } } } }, "responses": { "200": { "description": "SSL certificate details", "headers": { "X-Credits-Remaining": { "$ref": "#/components/headers/XCreditsRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "domain": { "type": "string" }, "valid": { "type": "boolean" }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_to": { "type": "string", "format": "date-time" }, "days_remaining": { "type": "number" }, "sans": { "type": "array", "items": { "type": "string" } }, "hostname_match": { "type": "boolean" } } }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "domain": { "type": "string" }, "error": { "type": "string", "example": "connection_failed" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } } } }