# Focsec API Documentation

> API Documentation for the Focsec API, an IP threat detection API that identifies VPNs, proxies, TOR nodes, and malicious bots. For general product information, pricing, and registration visit [focsec.com](https://focsec.com).

## API Overview

- RESTful API, HTTPS only, all responses are JSON
- Base URL: `https://api.focsec.com/v1/`
- API status: https://focsec.instatus.com/

## Authentication

API requests require an API key. Two methods:

1. **HTTP Authorization header (recommended):** `Authorization: your-api-key-here`
2. **URL query parameter:** `?api_key=your-api-key-here`

The API key is secret. Do not expose it client-side.

## Endpoints

### Check IP

`GET https://api.focsec.com/v1/ip/<ip-address>`

Example: `GET https://api.focsec.com/v1/ip/82.40.11.200`

#### Response fields

| Field | Type | Description |
|---|---|---|
| ip | string | The queried IP address |
| is_vpn | bool | IP is associated with a VPN service |
| is_proxy | bool | IP is associated with a proxy service |
| is_bot | bool | IP is a known malicious bot |
| is_tor | bool | IP is a TOR exit node |
| is_datacenter | bool | IP belongs to a datacenter, cloud, or hosting provider |
| city | string | Approximate city |
| country | string | Country name |
| iso_code | string | ISO 3166 two-letter country code |
| is_in_european_union | bool | Whether the country is an EU member state |
| flag | string | Emoji flag of the country |
| autonomous_system_number | int | AS number managing the IP |
| autonomous_system_organization | string | AS organization name |

#### Example response

```json
{
  "ip": "82.40.11.200",
  "is_vpn": false,
  "is_proxy": true,
  "is_bot": false,
  "is_tor": false,
  "is_datacenter": true,
  "city": "Berlin",
  "country": "Germany",
  "iso_code": "de",
  "is_in_european_union": true,
  "flag": "\ud83c\udde9\ud83c\uddea",
  "autonomous_system_number": 6830,
  "autonomous_system_organization": "N1 Network Solutions"
}
```

### Download Database (Enterprise only)

`GET https://api.focsec.com/v1/database/<database_name>.<format>.gz`

Example: `GET https://api.focsec.com/v1/database/vpn.txt.gz`

- **database_name:** `all`, `vpn`, `proxy`, `bot`, `tor`
- **format:** `txt`, `csv`, `jsonl`

Response is a gzipped file in the requested format. Returns 400 if the database name is invalid.

## Errors

### Client errors

| Code | Type | Meaning |
|---|---|---|
| 400 | Bad Request | Invalid request, check response body |
| 401 | Unauthorized | API key missing or invalid |
| 402 | Payment Required | Subscription or trial expired |
| 404 | Not Found | URL not found |
| 405 | Method Not Allowed | HTTP method not supported for this URL |
| 429 | Too Many Requests | Daily request limit exceeded |

### Server errors

| Code | Type | Meaning |
|---|---|---|
| 500 | Internal Server Error | Server-side processing failure |
| 502 | Bad Gateway | API temporarily unavailable |
| 503 | Service Unavailable | API temporarily unavailable |

## Request Limits

Daily limits are included in response headers and reset at midnight UTC:

| Header | Meaning |
|---|---|
| X-RequestLimit-RequestsMadeToday | Requests made today |
| X-RequestLimit-RequestsRemainingToday | Requests remaining today |

## Notes

- Results may contain false positives or false negatives. See [terms](https://focsec.com/terms).

## Links

- [Full documentation](https://docs.focsec.com)
- [Register / Sign in](https://focsec.com)
- [Contact](https://focsec.com/contact)
- [Terms](https://focsec.com/terms)
- [Privacy](https://focsec.com/privacy)