Network & infrastructure

Scraper

Fetches meta and OGP information from a URL.

MCP tool: network.get_page_meta

GET /v1/scraper/meta

Parameters:

ParameterTypeRequiredDescription
urlstringURL to fetch (http/https only)

Request example:

curl "https://api.thousand-api.com/v1/scraper/meta?url=https://example.com" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "description": "This domain is for use in illustrative examples.",
  "favicon": "https://example.com/favicon.ico",
  "ogp": {
    "title": null,
    "description": null,
    "image": null,
    "url": null,
    "site_name": null,
    "type": null
  },
  "canonical": "https://example.com/"
}

ExchangeRate

Returns real-time exchange rates and currency conversion.

MCP tool: network.get_exchange_rate

GET /v1/exchangerate

Parameters:

ParameterTypeRequiredDescription
fromstringSource currency code (e.g. JPY)
tostringTarget currency code (e.g. USD)
amountnumber-Amount to convert (defaults to 1)

Request example:

curl "https://api.thousand-api.com/v1/exchangerate?from=JPY&to=USD&amount=1000" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "from": "JPY",
  "to": "USD",
  "rate": 0.0067,
  "amount": 1000,
  "converted": 6.7,
  "timestamp": "2026-05-20T00:00:00.000Z",
  "cache_ttl": 60,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

Postal Lookup

Bidirectional lookup of Japanese postal codes and addresses. Forward lookup: postal code → full address. Reverse lookup: address keyword → matching postal codes. Uses official Japan Post data (~120k records), so it covers newly created and discontinued codes that LLMs may not know.

MCP tool: network.lookup_postal_code

The country parameter is designed for future international support. Currently only JP (Japan) is supported.

GET /v1/postal/lookup

Parameters:

ParameterTypeRequiredDescription
codestring-Postal code for forward lookup. 7 digits or XXX-XXXX (e.g. 358-0001)
addressstring-Address keyword for reverse lookup. Partial match on prefecture, city, town, or kana (e.g. 向陽台, 入間)
countrystring-Country code (default: JP). Currently JP only
limitinteger-Max results for reverse lookup (default: 10, max: 50)

Response fields:

ParameterDescription
queryRequest parameters (code / address / country)
resultsMatching postal records
results[].codePostal code without hyphen (7 digits)
results[].code_formattedPostal code with hyphen
results[].prefecturePrefecture name
results[].prefecture_kanaPrefecture name in katakana
results[].cityCity / ward name
results[].city_kanaCity name in katakana
results[].townTown / district name
results[].town_kanaTown name in katakana
results[].full_addressPrefecture + city + town combined
results[].countryCountry code
countNumber of results returned
truncatedWhether results were limited by limit (reverse lookup only)
cache_ttlRecommended cache duration in seconds (604800 = 7 days)
cached_atData fetch time (ISO 8601). Use to decide whether to refetch

Request example:

Example 1: Forward lookup (postal code → address)

curl "https://api.thousand-api.com/v1/postal/lookup?code=358-0001" \
  -H "x-api-key: YOUR_API_KEY"
{
  "query": { "code": "358-0001", "country": "JP" },
  "results": [
    {
      "code": "3580001",
      "code_formatted": "358-0001",
      "prefecture": "埼玉県",
      "prefecture_kana": "サイタマケン",
      "city": "入間市",
      "city_kana": "イルマシ",
      "town": "向陽台",
      "town_kana": "コウヨウダイ",
      "full_address": "埼玉県入間市向陽台",
      "country": "JP"
    }
  ],
  "count": 1,
  "truncated": false,
  "cache_ttl": 604800,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

Example 2: Reverse lookup by city (multiple matches)

curl "https://api.thousand-api.com/v1/postal/lookup?address=%E5%85%A5%E9%96%93%E5%B8%82" \
  -H "x-api-key: YOUR_API_KEY"
{
  "query": { "address": "入間市", "country": "JP" },
  "results": [
    {
      "code": "3580001",
      "code_formatted": "358-0001",
      "prefecture": "埼玉県",
      "city": "入間市",
      "town": "向陽台",
      "full_address": "埼玉県入間市向陽台",
      "country": "JP"
    }
  ],
  "count": 10,
  "truncated": true
}

Example 3: Reverse lookup by town (partial match)

curl "https://api.thousand-api.com/v1/postal/lookup?address=%E5%90%91%E9%99%BD%E5%8F%B0" \
  -H "x-api-key: YOUR_API_KEY"
{
  "query": { "address": "向陽台", "country": "JP" },
  "results": [
    {
      "code": "3580001",
      "code_formatted": "358-0001",
      "prefecture": "埼玉県",
      "city": "入間市",
      "town": "向陽台",
      "full_address": "埼玉県入間市向陽台",
      "country": "JP"
    }
  ],
  "count": 1,
  "truncated": false
}

IPLookup

Returns geographic information for an IP address (country, region, city, coordinates).

MCP tool: network.get_ip_info

GET /v1/iplookup

Parameters:

ParameterTypeRequiredDescription
addressstring-IP address to look up (defaults to the request source IP)

Request example:

curl "https://api.thousand-api.com/v1/iplookup?address=8.8.8.8" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "is_valid": true,
  "address": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "zip": "94043",
  "lat": 37.4223,
  "lon": -122.0847
}

URL Resolve

Follows HTTP redirects to the final URL. Use for short links, affiliate URLs, and link safety checks. Combine with the Scraper tool to fetch page metadata after resolving.

MCP tool: network.resolve_url

GET /v1/url/resolve

Parameters:

ParameterTypeRequiredDescription
urlstringURL to resolve (http/https only)

The url query parameter must be URL-encoded (e.g. https://bit.ly/xxxxx → https%3A%2F%2Fbit.ly%2Fxxxxx).

Request example:

curl "https://api.thousand-api.com/v1/url/resolve?url=https%3A%2F%2Fbit.ly%2Fxxxxx" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "original": "https://bit.ly/xxxxx",
  "final": "https://example.com/product/123",
  "redirects": [
    "https://bit.ly/xxxxx",
    "https://example.com/product/123"
  ],
  "redirect_count": 1,
  "has_redirect": true
}

Response fields:

ParameterDescription
originalRequested URL
finalFinal URL after following redirects
redirectsOrdered list of URLs visited (from original to final)
redirect_countNumber of redirects (redirects.length - 1)
has_redirectTrue when at least one redirect was followed
truncatedPresent and true when the 10-hop limit was reached

Response:

Only http and https are followed. Each hop times out after 5 seconds. Up to 10 redirects; when the limit is reached, truncated is true.

URL Health Check

Checks a URL's HTTP status code, response time, and SSL certificate details. Combine with network.resolve_url to inspect the final destination of shortened URLs.

MCP tool: network.inspect_url

GET /v1/url/inspect

Parameters:

ParameterTypeRequiredDescription
urlstringURL to inspect (http/https only)

Request example:

curl "https://api.thousand-api.com/v1/url/inspect?url=https%3A%2F%2Fwww.thousand-api.com" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "url": "https://www.thousand-api.com",
  "status_code": 200,
  "response_time_ms": 234,
  "reachable": true,
  "headers": {
    "content-type": "text/html",
    "x-frame-options": "DENY"
  },
  "ssl": {
    "valid": true,
    "expires_at": "2027-01-01T00:00:00.000Z",
    "days_remaining": 220,
    "issuer": "Amazon"
  }
}

DNS Lookup

Look up DNS records for a domain. Supports A, AAAA, CNAME, MX, TXT, and NS using Node.js built-in dns (no external dependencies).

MCP tool: network.dns_lookup

GET /v1/dns/lookup

Parameters:

ParameterTypeRequiredDescription
domainstringDomain name to look up
typestring-A / AAAA / CNAME / MX / TXT / NS / all (default: all)

Request example:

curl "https://api.thousand-api.com/v1/dns/lookup?domain=example.com&type=all" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "domain": "example.com",
  "type": "all",
  "records": {
    "A": ["93.184.216.34"],
    "NS": ["a.iana-servers.net", "b.iana-servers.net"],
    "TXT": ["v=spf1 -all"]
  }
}

Calc CIDR

Calculate IPv4 CIDR block details in one call: network and broadcast addresses, subnet and wildcard masks, usable host range, and host counts. Helps avoid common LLM mistakes when designing AWS VPC subnets, security groups, or firewall rules. Pure bit arithmetic with no external libraries.

MCP tool: network.calc_cidr

GET /v1/network/cidr/calc

Parameters:

ParameterTypeRequiredDescription
cidrstringRequiredIPv4 CIDR notation (e.g. 192.168.1.0/24)

Response fields:

ParameterDescription
cidrNormalized CIDR (host inputs are corrected to the network address)
ip_versionIP version (currently 4 only)
prefix_lengthPrefix length (0–32)
network_addressNetwork address
broadcast_addressBroadcast address
subnet_maskSubnet mask
wildcard_maskWildcard mask (used in ACLs, etc.)
first_hostFirst usable host (null for /31 and /32)
last_hostLast usable host (null for /31 and /32)
total_addressesTotal addresses (2^(32-prefix))
usable_hostsUsable host count (/32=1, /31=2, /30 and below=total-2)
is_privateWhether the block is in RFC 1918 private space (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)

Basic (192.168.1.0/24):

A typical private /24 subnet with 254 usable hosts.

curl "https://api.thousand-api.com/v1/network/cidr/calc?cidr=192.168.1.0%2F24" \
  -H "x-api-key: YOUR_API_KEY"
{
  "cidr": "192.168.1.0/24",
  "ip_version": 4,
  "prefix_length": 24,
  "network_address": "192.168.1.0",
  "broadcast_address": "192.168.1.255",
  "subnet_mask": "255.255.255.0",
  "wildcard_mask": "0.0.0.255",
  "first_host": "192.168.1.1",
  "last_host": "192.168.1.254",
  "total_addresses": 256,
  "usable_hosts": 254,
  "is_private": true
}

Large VPC (10.0.0.0/8):

Class A private address space with about 16.7 million addresses.

curl "https://api.thousand-api.com/v1/network/cidr/calc?cidr=10.0.0.0%2F8" \
  -H "x-api-key: YOUR_API_KEY"
{
  "cidr": "10.0.0.0/8",
  "ip_version": 4,
  "prefix_length": 8,
  "network_address": "10.0.0.0",
  "broadcast_address": "10.255.255.255",
  "subnet_mask": "255.0.0.0",
  "wildcard_mask": "0.255.255.255",
  "first_host": "10.0.0.1",
  "last_host": "10.255.255.254",
  "total_addresses": 16777216,
  "usable_hosts": 16777214,
  "is_private": true
}

Check IP In Range

Check whether a given IPv4 address falls within one or more CIDR blocks using bit-mask arithmetic. Avoids common LLM mistakes when verifying IP membership across subnets. Pair with network.calc_cidr: inspect network/broadcast boundaries and host counts first, then use this API to verify whether a specific IP belongs to a range.

MCP tool: network.check_ip_in_range

GET /v1/network/ip/in-range

Parameters:

ParameterTypeRequiredDescription
ipstringRequiredIPv4 address to check (e.g. 192.168.1.100)
rangesstringRequiredComma-separated CIDR list, max 100 (e.g. 192.168.1.0/24,10.0.0.0/8)

Response fields:

ParameterDescription
ipChecked IPv4 address
resultsPer-range results array with range and contains
any_matchTrue when at least one range contains the IP
matching_rangesCIDR notations where contains is true

Basic (private subnet IP):

192.168.1.100 is inside 192.168.1.0/24 but not inside 10.0.0.0/8.

curl "https://api.thousand-api.com/v1/network/ip/in-range?ip=192.168.1.100&ranges=192.168.1.0%2F24%2C10.0.0.0%2F8" \
  -H "x-api-key: YOUR_API_KEY"
{
  "ip": "192.168.1.100",
  "results": [
    { "range": "192.168.1.0/24", "contains": true },
    { "range": "10.0.0.0/8", "contains": false }
  ],
  "any_match": true,
  "matching_ranges": ["192.168.1.0/24"]
}

Check Domain Format

Validates whether a domain name is well-formed per RFC 1035 / RFC 1123 (label length, character set, IDN/Punycode) and returns its structure (labels / tld). Does not perform DNS resolution.

MCP tool: network.check_domain_format

POST /v1/network/check-domain-format

Parameters:

ParameterTypeRequiredDescription
domainstringRequiredDomain name to validate (e.g. example.com / 例え.com). Does not resolve DNS

Response fields:

ParameterDescription
validTrue when the domain is well-formed
domainInput after trim and trailing-dot removal
labelsLabel array used for validation (null when invalid)
tldLast label (not PSL-aware; null when invalid)
is_idnTrue when the domain has non-ASCII or xn-- labels
punycodeASCII/Punycode form when is_idn is true; otherwise null
error_reasonHuman-readable reason when valid is false (null on success)

ASCII domain (valid):

Typical ASCII domain validation.

curl -X POST "https://api.thousand-api.com/v1/network/check-domain-format" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "thousand-api.com"}'
{
  "valid": true,
  "domain": "thousand-api.com",
  "labels": ["thousand-api", "com"],
  "tld": "com",
  "is_idn": false,
  "punycode": null,
  "error_reason": null
}

Japanese IDN:

Non-ASCII domains are converted to Punycode before format checks; punycode and labels are returned.

curl -X POST "https://api.thousand-api.com/v1/network/check-domain-format" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "例え.com"}'
{
  "valid": true,
  "domain": "例え.com",
  "labels": ["xn--r8jz45g", "com"],
  "tld": "com",
  "is_idn": true,
  "punycode": "xn--r8jz45g.com",
  "error_reason": null
}

Invalid format:

Malformed domains still return HTTP 200 with valid: false and error_reason (empty or extremely long inputs yield VALIDATION_ERROR).

curl -X POST "https://api.thousand-api.com/v1/network/check-domain-format" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "-invalid-.com"}'
{
  "valid": false,
  "domain": "-invalid-.com",
  "labels": null,
  "tld": null,
  "is_idn": false,
  "punycode": null,
  "error_reason": "ラベルの先頭または末尾にハイフンは使用できません"
}

HTTP Fetch

Sends an HTTP request to an external URL and returns the status code, headers, and body. Supports GET, POST, PUT, PATCH, DELETE, and HEAD with optional custom headers and body. Useful when an agent needs to call authenticated APIs on your behalf.

MCP tool: network.http_fetch

POST /v1/http/fetch

Parameters:

ParameterTypeRequiredDescription
urlstringRequiredRequest URL (http:// or https:// only)
methodstringOptionalHTTP method (GET / POST / PUT / PATCH / DELETE / HEAD; default GET)
headersobjectOptionalRequest headers to send (Host, X-Forwarded-* are stripped)
bodystringOptionalRequest body for POST / PUT / PATCH
timeout_msintegerOptionalTimeout in milliseconds (default 10000, max 30000)

Response fields:

ParameterDescription
status_codeHTTP status code from the upstream server
headersResponse headers as a key-value object
bodyResponse body as text (max 1MB)
response_time_msElapsed milliseconds from request start to response
truncatedTrue when the body exceeded 1MB and was truncated

Request example:

curl -X POST "https://api.thousand-api.com/v1/http/fetch" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/",
    "method": "GET"
  }'

Response example:

{
  "status_code": 200,
  "headers": {
    "content-type": "text/html; charset=UTF-8"
  },
  "body": "<!doctype html>...",
  "response_time_ms": 245,
  "truncated": false
}