# IP-Info API

> IP geolocation and network intelligence API: country, city, timezone, ASN, and network ownership for IPv4 and IPv6 addresses.

The API is served at `https://api.ip-info.app` (the same API is also reachable same-origin at `https://ip-info.app/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://ip-info.app/open-api
- MCP integration guide for AI agents: https://ip-info.app/guides/mcp-server
- OpenAPI document (machine-readable, this is the contract): https://ip-info.app/json/open-api.json
- Pricing and credit packs: https://ip-info.app/pricing
- Live demo in the browser: https://ip-info.app/try
- Guides: https://ip-info.app/guides
- Technical articles: https://ip-info.app/blog

## MCP server for AI agents

- Endpoint: https://api.ip-info.app/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` is free; HTTP 402 means out of credits (top up at https://ip-info.app/pricing)
- Tools: - account_whoami (free identity probe)
- ip_get_details (geolocation + ASN; provider maxmind|geojs; defaults to caller IP)
- Discovery: https://ip-info.app/.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://ip-info.app/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 IP lookup requests. Use this endpoint from an authenticated account session.
- `POST /v1-delete-api-key` — Delete an API key: Permanently delete an API key from your account. Deleted keys can no longer authenticate lookup requests.
- `POST /v1-get-api-key-details` — Get API key details: Fetch one API key by ID, including enabled state, service access, and metadata.
- `POST /v1-list-api-keys` — List API keys: List API keys available in your authenticated IP-Info account.
- `POST /v1-update-api-key` — Update an API key: Update an API key name, enabled state, environment label, or IP Info service access.
- `GET /v1-who-am-i` — Identify the current credential: Return account and request context for the API key or account token used on the request.

### Usage
- `GET /v1-download-api-usage` — Export API usage: Create a downloadable usage export for a date range. Use this for reporting, reconciliation, or cost tracking.
- `GET /v1-get-api-usage` — Get API usage: Return daily API usage rows for your authenticated account, optionally filtered by date range and service.

### IP Lookup
- `GET /v1-get-ip-details` — Look up IP details: Resolve an IPv4 or IPv6 address into geolocation, registered country, ASN, organization, PTR hostname, and optional lookup timing details. If `ip` is omitted, t

## Workflows

- Fraud screening — geo and ASN mismatches flag suspicious logins and payments.
- Geo routing and localization — localize currency, language, and content from the resolved country and timezone.
- Traffic analytics — enrich request logs with ASN and organization for network attribution.
- Compliance and geo-controls — enforce regional restrictions with country codes.

## 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.