# Ops.Tools API Reference

> Domain and network operations API for production applications: DNS lookup, WHOIS, SSL certificate checks, HTTP response analysis, and TCP port scanning.

The API is served at `https://api.ops.tools` (the same API is also reachable same-origin at `https://ops.tools/api`). All endpoints authenticate with an `x-api-key` header and are billed per call.

## Start here

- Interactive API reference (with one-click MCP install buttons): https://ops.tools/open-api
- MCP integration guide for AI agents: https://ops.tools/guides/mcp-server
- OpenAPI document (machine-readable, this is the contract): https://ops.tools/json/open-api.json
- Pricing and credit packs: https://ops.tools/pricing
- Live demo in the browser: https://ops.tools/try
- Guides: https://ops.tools/guides
- Technical articles: https://ops.tools/blog

## MCP server for AI agents

- Endpoint: https://api.ops.tools/mcp
- Transport: Streamable HTTP — POST JSON-RPC 2.0, header `Accept: application/json, text/event-stream`
- Auth: `x-api-key` header with a product API key (host-scoped; cross-product keys are rejected with A1003)
- Demo access: key `demo-key` with a valid TOTP in `x-ct` (rate-limited, evaluation only)
- Billing: 1 credit per tool call; `account_whoami` and `account_usage` are free; HTTP 402 means out of credits (top up at https://ops.tools/pricing)
- Tools: - account_whoami (free — identity + creditAvailable/creditUsed)
- account_usage (free — daily usage by service)
- ops_dns_lookup
- ops_whois
- ops_ssl_check
- ops_http_analyze
- ops_port_scan (available on request)
- Discovery: https://ops.tools/.well-known/mcp/server-card.json · this llms.txt · the Scalar MCP panel on /open-api
- Supported clients: Claude Code, Claude (claude.ai + Desktop), Codex (CLI, IDE extension, ChatGPT desktop app), Cursor, VS Code (Copilot), Windsurf, Cline, Continue, Zed, Gemini CLI, and any client that speaks Streamable HTTP.
- The server returns agent instructions in the MCP initialize result.

## Authentication and errors

- `x-api-key` header (or `x-api-key` query parameter) — create keys at https://ops.tools/account/api-keys. Keys are scoped to this product host.
- `x-jwt-token` header — session alternative; when both are present the API key wins.
- Error envelope: `{ "error": "CODE", "message": "...", "issues": [...] }`. Auth codes: A1001 missing credential, A1002 malformed key, A1003 unknown/disabled key or cross-host key, A1004 invalid TOTP, A1006 unverified account, A1008 authentication required, A1009 admin required.
- Rate limits: guest limits are strict and per-IP; authenticated keys get plan-based limits (429 with Retry-After when exceeded).

## API endpoints

### API Keys
- `POST /v1-create-api-key` — Create an API key: Create a new API key for your account. Use services to limit which Ops.Tools API products the key can call.
- `POST /v1-delete-api-key` — Delete an API key: Permanently delete an API key owned by your account.
- `POST /v1-get-api-key-details` — Get API key details: Retrieve the settings and status for one API key owned by your account.
- `POST /v1-list-api-keys` — List API keys: List the API keys available to your account.
- `POST /v1-update-api-key` — Update an API key: Change an API key name, environment, service access, or enabled state.
- `GET /v1-who-am-i` — Inspect the current API key: Return account and request context for the API key used on the request.

### Usage
- `GET /v1-download-api-usage` — Export API usage: Create a downloadable usage export for a date range and optional service filter.
- `GET /v1-get-api-usage` — List API usage: Return daily usage totals for your account, optionally filtered by date range and service.

### IP Lookup
- `GET /v1-get-ip-details` — Look up IP details: Resolve location, ASN, organization, and optional performance details for an IP address.

### DNS
- `GET /v1-dns-lookup` — Look up DNS records: Resolve DNS records for a domain or hostname. Choose a record type such as A, AAAA, MX, TXT, NS, CNAME, or ANY.

### WHOIS
- `GET /v1-whois-data` — Look up WHOIS data: Retrieve raw WHOIS registration data for a domain, with optional parsed JSON fields.

### SSL
- `GET /v1-ssl-checker` — Check an SSL certificate: Inspect certificate validity, expiry, issuer, subject names, TLS protocol, and chain details for a domain.

### HTTP Analysis
- `GET /v1-analyze-http` — Analyze an HTTP endpoint: Inspect a URL for redirects, headers, security recommendations, caching, and response metadata.

### Port Scanner
- `GET /v1-port-scanner` — Scan ports: Check whether selected TCP ports are open, closed, or filtered on a domain or IP address.

## Workflows

- Incident triage — run ops_dns_lookup and ops_ssl_check when a site goes down; record the evidence.
- Certificate expiry monitoring — schedule ops_ssl_check and alert before daysRemaining runs out.
- Security review — ops_http_analyze grades security headers; ops_port_scan checks exposure (authorized assets only).
- Domain portfolio operations — ops_whois tracks registration dates and name-server changes.

## Notes for agents

- All lookups are read-only and cache-backed; pass `skipCache=true` only when freshness matters.
- The bulk JSON upload endpoints run asynchronously: upload, poll list status, then download results.
- Tool calls over MCP and REST calls cost the same credits and return the same data shapes.