# PulseWise API

> PulseWise is a license-key-gated REST API providing IP geolocation, weather, WHOIS, SSL, DNS, ping, and network lookup services. All API requests require a `pk_`-prefixed license key passed via the `X-License-Key` header or `?api_key=` query parameter.

Authentication uses license keys created from the user dashboard. Each key has a plan tier (FREE, BASIC, PREMIUM, ENTERPRISE) that determines hourly rate limits and total request quotas. Optional IP and domain allowlists can further restrict a key.

Base URL: https://pulsewise.com

## Authentication

- [Register](https://pulsewise.com/register): Create an account (requires email verification + reCAPTCHA)
- [Login](https://pulsewise.com/login): Sign in to manage API keys and billing
- [API Key Management](https://pulsewise.com/api-keys): Generate, configure, and revoke `pk_` license keys

Pass the key on every API call:

```
GET https://pulsewise.com/v1/ip/8.8.8.8
X-License-Key: pk_your_key_here
```

## API Endpoints (v1)

All endpoints below require a valid license key and return JSON.

- [GET /v1/ip/{ip?}](https://pulsewise.com/api/v1/ip): IP details for the given address (defaults to caller's IP)
- [GET /v1/server/{target}](https://pulsewise.com/api/v1/server): Combined server/network diagnostics for a host
- [GET /v1/location/{city?}/{region?}/{country?}](https://pulsewise.com/api/v1/location): Forward geocoding lookup
- [GET /v1/weather/{lat}/{lon}](https://pulsewise.com/api/v1/weather): Current weather at given coordinates
- [GET /v1/services/whois/{domain}](https://pulsewise.com/api/v1/services/whois): WHOIS registration data
- [GET /v1/services/ssl/{domain}](https://pulsewise.com/api/v1/services/ssl): SSL/TLS certificate inspection
- [GET /v1/services/dns/{domain}](https://pulsewise.com/api/v1/services/dns): DNS record lookup
- [GET /v1/services/ping/{target}](https://pulsewise.com/api/v1/services/ping): ICMP reachability check
- [GET /v1/services/geolocation/{ip}](https://pulsewise.com/api/v1/services/geolocation): Geolocation for an IP

## Simplified Endpoints

Same services available without the `/v1/services/` prefix:

- GET /whois/{domain}
- GET /ssl/{domain}
- GET /dns/{domain}
- GET /ping/{target}
- GET /geolocation/{ip}

## Rate Limits & Plans

Rate limits are enforced per license key, per hour. Plan tiers and quotas are managed through subscription billing (Stripe).

- [Subscription Plans](https://pulsewise.com/api/subscription/plans): Available tiers and pricing (public endpoint, no key required)

## Response Format

All endpoints return JSON of the shape:

```
{
  "success": true,
  "data": { ... },
  "timestamp": "2026-05-04T12:00:00Z"
}
```

Errors return `success: false` with an `error.message` field and an appropriate HTTP status code (400, 401, 403, 404, 429, 500).

## Optional

- [Documentation](https://pulsewise.com/api/docs): Full interactive API documentation
- [Terms of Service](https://pulsewise.com/terms-of-service)
- [Privacy Policy](https://pulsewise.com/privacy-policy)