API Documentation

Authentication

Every request to the VectraIP API must include your API key in the X-API-Key header.

HTTP Header

X-API-Key: vip_live_YOUR_KEY_HERE

API keys can be created at /signup. Keys are prefixed with vip_live_. The full key is shown only once at creation time.

Errors

All errors follow a consistent JSON envelope:

Error response

{
  "detail": "Invalid IP address: 999.999.999.999"
}

Status	Meaning
400	Bad request — invalid IP, malformed body
401	Missing or invalid API key
403	Key revoked or quota exceeded
422	Validation error (Pydantic)
429	Rate limit exceeded
500	Internal server error

Rate Limits

Rate limits are enforced per API key using a sliding 60-second window. Limits depend on your plan:

Plan	Requests / minute	Monthly quota
Free	10	1,000
Developer	60	50,000
Business	300	500,000
Enterprise	1,000+	Unlimited

When a rate limit is hit the API returns HTTP 429 with a Retry-After header.

IP Lookup

GET /v1/ip/{ip}

Returns the full enriched intelligence response for a single IP address. Supports IPv4 and IPv6. Private, loopback and reserved addresses are rejected.

Example request

curl https://api.vectraip.com/v1/ip/45.130.202.105 \
  -H "X-API-Key: vip_live_YOUR_KEY"

Example response (200 OK)

{
  "query": {
    "ip": "45.130.202.105",
    "processed_at": "2026-05-25T14:00:00Z",
    "cache_status": "miss",
    "request_id": "req_a1b2c3d4"
  },
  "privacy": {
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": false,
    "is_relay": false,
    "risk_score": 72
  },
  "geo": {
    "country_code": "TR",
    "country_name": "Turkey",
    "region": "Bursa",
    "city": "Bursa",
    "timezone": "Europe/Istanbul",
    "continent": "Asia",
    "coordinates": { "lat": 40.19, "lng": 29.06 }
  },
  "network": {
    "asn": "AS137409",
    "organization": "GSL Networks Pty LTD",
    "cidr": "45.130.202.0/23",
    "connection_type": "hosting",
    "usage_type": "hosting",
    "traffic_class": "vpn_exit"
  },
  "monitoring": {
    "detected": false,
    "provider": null
  },
  "risk": {
    "score": 74,
    "level": "high",
    "fraud_probability": 70,
    "bot_probability": 45,
    "abuse_probability": 60,
    "vpn_confidence": 80,
    "residential_trust": 15,
    "synthetic_traffic_probability": 10
  },
  "meta": {
    "response_time_ms": 42,
    "data_sources": ["vpnapi.io", "maxmind", "vectraip_internal"]
  }
}

Batch Lookup

POST /v1/batch/ip

Enrich up to 100 IP addresses in a single request. All IPs are processed concurrently. Duplicates are deduplicated automatically.

Request body

{
  "ips": ["8.8.8.8", "1.1.1.1", "45.130.202.105"]
}

Response (200 OK)

{
  "results": [ /* array of IPEnrichmentResponse */ ],
  "processed": 3,
  "errors": 0
}

Create API Key

POST /v1/keys

Request body

{
  "label": "My App",
  "owner_email": "[email protected]"
}

The raw API key is returned once only. Store it securely.

New keys are issued on the free plan. Upgrade to a paid plan from your dashboard.

Rotate API Key

POST /v1/keys/{key_id}/rotate

Revokes the existing key and issues a new one with the same plan, label and owner. The new raw key is returned once.

Revoke API Key

DELETE /v1/keys/{key_id}

Permanently deactivates the key. Cannot be undone.

Key Usage

GET /v1/keys/{key_id}/usage

Returns quota, rate limit, request count and last used timestamp for a key.

Response: query

Field	Type	Description
ip	string	The queried IP address
processed_at	ISO 8601	Timestamp of the request
cache_status	string	`hit`, `db_hit`, or `miss`
request_id	string	Unique trace ID (X-Request-Id header)

Response: privacy

Field	Type	Description
is_vpn	bool	VPN exit node detected
is_proxy	bool	Proxy server detected
is_tor	bool	Tor exit node detected
is_relay	bool	Apple Private Relay detected
risk_score	int (0–100)	Provider-level risk score

Response: risk

Field	Type	Description
score	int (0–100)	Composite risk score
level	string	`low` / `medium` / `high` / `critical`
fraud_probability	int (0–100)	Likelihood of fraud activity
bot_probability	int (0–100)	Likelihood of automated bot traffic
abuse_probability	int (0–100)	Likelihood of abuse/spam activity
datacenter_risk	int (0–100)	Risk contribution from datacenter/hosting signals
vpn_confidence	int (0–100)	Confidence that a VPN/relay is in use
residential_trust	int (0–100)	Trust score for residential IPs (inverse of risk)
synthetic_traffic_probability	int (0–100)	Likelihood of synthetic/monitoring traffic

Response: monitoring

Field	Type	Description
detected	bool	Whether this IP belongs to a monitoring provider
provider	string \| null	Provider name (e.g. `UptimeRobot`)
category	string \| null	e.g. `synthetic_monitoring`
confidence	string \| null	`high` / `medium` / `low`
first_seen	ISO 8601 \| null	When this CIDR was first indexed
last_seen	ISO 8601 \| null	Last confirmation timestamp