API Guide

Integrate mlab into your security workflows with the REST API to automate lookups, submit files and retrieve results programmatically.

Integrate mlab into your security workflows with the REST API. Automate lookups, submit files and retrieve results programmatically.

Authentication

All API requests require an API key passed in the Authorization header. You can generate your API key from your account settings (Pro plan or above required).

# Include your API key in every request
GET https://mlab.sh/api/v1/scan/ip?ip=8.8.8.8
Authorization: Bearer YOUR_API_KEY

Your API key is tied to your account and shares your daily scan quotas. Keep it secure and never expose it in client-side code.

Rate limits

API requests count against your plan's daily scan quotas. When you exceed your daily limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Plan	Domain scans	IP scans	File scans
Pro	25 / day	50 / day	20 / day
Team	100 / day	200 / day	80 / day
Enterprise	Custom - as you go

Each indicator type has its own lookup endpoint. There is no single combined search endpoint on the API: the search bar on the website is a router that redirects to these modules, so integrations call the specific endpoint they need.

Indicator	Endpoint	Counts against a quota
IP address	`GET /api/v1/scan/ip?ip={value}`	Yes (IP scans)
Crypto address	`GET /api/v1/scan/crypto?address={value}&chain={chain}`	Yes (crypto lookups)
MAC address	`GET /api/v1/scan/mac?mac={value}`	No
Email address	`GET /api/v1/scan/email?email={value}`	No
Phone number	`GET /api/v1/scan/phone?number={value}`	No

# Example: look up an IP address
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/ip?ip=185.220.101.47"

# Example: look up a crypto address.
# Pass `chain` for an EVM address: all 13 EVM chains share one address format,
# so it cannot be derived, and omitting it defaults to Ethereum.
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/crypto?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ETH"

# Example: look up a MAC address
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/mac?mac=00:0C:29:1A:2B:3C"

# Example: look up an email address
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/[email protected]"

# Example: look up a phone number (the '+' is URL-encoded as %2B)
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/phone?number=%2B33612345678"

MAC, email and phone lookups are computed locally and do not count against a scan quota. IP and crypto lookups draw on live intelligence and count against your plan's daily quotas. Domain and file analysis use the scan endpoints below. Hash, URL and CVE lookups are available on the website only and have no API endpoint yet.

Each lookup accepts a single indicator and returns the same data as the matching module on the website. See the per-module pages under Scans & Lookups for the exact response fields.

Scan a domain

Launch a full domain scan, then poll for its result.

POST /api/v1/scan/domain
Content-Type: application/json

# Example: start a domain scan
curl -X POST \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain":"example.com"}' \
    "https://mlab.sh/api/v1/scan/domain"

# Retrieve the results once the scan has completed
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/domain/results?domain=example.com"

Submit a file for analysis

Upload a file (max 10 MB) for scanning and analysis.

POST /api/v1/file/upload
Content-Type: multipart/form-data

# Example: upload a suspicious binary
curl -X POST \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "[email protected]" \
    "https://mlab.sh/api/v1/file/upload"

Get scan results

Retrieve the results of a previous scan by its ID.

GET /api/v1/scan/{scan_id}

# Example: retrieve a domain scan result
curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://mlab.sh/api/v1/scan/abc123def456"

Response format

All API responses are returned as JSON. Successful requests return a 200 status with a data object. Errors return an appropriate HTTP status code with a message field.

// Successful response
{
  "status": "ok",
  "data": { ... }
}

// Error response
{
  "status": "error",
  "message": "Rate limit exceeded",
  "code": 429
}

HTTP status codes

Code	Meaning
`200`	Success - result returned
`400`	Bad request - invalid parameter or missing required field
`401`	Unauthorized - missing or invalid API key
`403`	Forbidden - your plan does not include API access
`404`	Not found - scan ID does not exist
`429`	Rate limited - daily quota exceeded, check `Retry-After` header
`500`	Server error - please retry or contact support