Authentication
Authenticate your API requests with an API key.
All API requests are made to https://mlab.sh/api/v1/ and must include your API key in the Authorization header.
header format
Authorization: token mlab_your_api_key_here
Generate an API Key
- Log in to mlab.sh
- Go to Account > Settings > API Keys
- Click Create API Key, give it a descriptive note
- Copy the key — it is only shown once
Keep your API key secret. Do not commit it to version control or share it publicly. If compromised, delete it immediately and create a new one.
Quick Start
Make your first API call in seconds.
Test your API key by calling the root endpoint:
terminal
curl -H "Authorization: token YOUR_API_KEY" \ https://mlab.sh/api/v1/
If your key is valid, you will get a greeting response:
response
{
"message": "Hello, anonymous user of YourOrganization!"
}
Base URL
| Environment | Base URL |
|---|---|
| Production | https://mlab.sh/api/v1 |
All endpoints described in this documentation are relative to this base URL.
Launch Scan
Launch an automated security scan on a domain.
| Method | POST |
| Endpoint | /scan/domain |
| Auth | API Key required |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | The domain to scan (e.g. example.com) |
example request
curl -X POST \ -H "Authorization: token YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"domain": "example.com"}' \ https://mlab.sh/api/v1/scan/domain
Response
200 OK
{
"status": "success",
"message": "Domain scan has been started."
}
400 Bad Request
{
"status": "error",
"message": "Provided domain is invalid."
}
// or
{
"status": "error",
"message": "Scan limit reached. Please try again later."
}
Scan Status
Check the progress of a domain scan.
| Method | GET |
| Endpoint | /scan/domain/status?domain=example.com |
| Auth | API Key required |
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | The domain to check |
example request
curl -H "Authorization: token YOUR_API_KEY" \ "https://mlab.sh/api/v1/scan/domain/status?domain=example.com"
Response
The status field indicates the scan progress:
| Status | Description |
|---|---|
pending | Scan is queued and has not started yet |
scanning | Scan is actively running |
success | Scan completed successfully |
200 OK
{
"status": "pending",
"message": "Domain scan is still pending."
}
// or
{
"status": "scanning",
"message": "Domain scan is still in progress."
}
// or
{
"status": "success",
"message": "Domain scan is in done."
}
Tip: poll this endpoint every few seconds after launching a scan to track its progress. Once the status is
success, retrieve the full results with /scan/domain/results.
Scan Results
Retrieve the full results of a completed domain scan.
| Method | GET |
| Endpoint | /scan/domain/results?domain=example.com |
| Auth | API Key required |
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | The domain to get results for |
example request
curl -H "Authorization: token YOUR_API_KEY" \ "https://mlab.sh/api/v1/scan/domain/results?domain=example.com"
Response
200 OK
{
"status": "completed",
"domain": "example.com",
"scan_date": "2026-03-23 10:30:00 UTC",
"results": {
"subdomains": ["www.example.com", "mail.example.com"],
"subdomains_suspicious": [
{ "keyword": "admin", "subdomain": "admin.example.com" }
],
"dns": {
"resolve": [
{
"domain": "example.com",
"a": ["93.184.216.34"],
"aaaa": ["2606:2800:220:1:..."],
"cname": null
}
],
"txt": {
"raw": ["v=spf1 include:..."],
"spf": "v=spf1 include:_spf.google.com ~all",
"dmarc": "v=DMARC1; p=reject; ...",
"dkim": []
}
},
"ssl": [
{
"domain": "example.com",
"issuer_name": "C=US, O=DigiCert Inc, ...",
"common_name": "www.example.org",
"not_before": "2024-01-30",
"not_after": "2025-03-01"
}
],
"files": {
"security_txt": "Contact: [email protected]\n...",
"robots_txt": "User-agent: *\nDisallow: /admin"
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
status | string | completed or in_progress |
results.subdomains | array | All discovered subdomains |
results.subdomains_suspicious | array | Subdomains flagged as suspicious (keyword + subdomain) |
results.dns.resolve | array | DNS A, AAAA and CNAME records per subdomain |
results.dns.txt | object | TXT records: raw, SPF, DMARC, DKIM |
results.ssl | array | SSL certificates found (issuer, dates, names) |
results.files.security_txt | string | Contents of security.txt (empty if not found) |
results.files.robots_txt | string | Contents of robots.txt (empty if not found) |
If
status is in_progress, some fields may be empty. Poll until completed for full results.
SSL Info
Retrieve SSL certificate information for a domain.
| Method | GET |
| Endpoint | /domain/ssl?domain=example.com |
| Auth | API Key required |
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | The domain to check SSL for |
example request
curl -H "Authorization: token YOUR_API_KEY" \ "https://mlab.sh/api/v1/domain/ssl?domain=example.com"
Returns SSL certificate details including issuer, validity dates, and certificate chain information.
Rate Limits
Understand and monitor your API usage limits.
API rate limits depend on your organization's subscription plan. You can check your remaining quota at any time.
| Method | GET |
| Endpoint | /limit/domain | /limit/ip | /limit/file |
| Auth | API Key or Session |
check domain scan limit
curl -H "Authorization: token YOUR_API_KEY" \ https://mlab.sh/api/v1/limit/domain
Scan Limits by Plan
| Plan | Domain scans | File scans | IP lookups |
|---|---|---|---|
free | Limited | Limited | Limited |
pro | Higher limits | Higher limits | Higher limits |
team | Extended | Extended | Extended |
enterprise | Custom | Custom | Custom |
When a scan limit is reached, the API returns a
400 error. Upgrade your plan on the pricing page for higher limits.
Errors
HTTP status codes and error handling.
The API uses standard HTTP status codes to indicate success or failure.
| Code | Meaning | Description |
|---|---|---|
200 | OK | Request succeeded |
400 | Bad Request | Missing or invalid parameters |
401 | Unauthorized | Invalid or missing API key |
404 | Not Found | Endpoint does not exist |
Error Response Format
Error responses are returned as JSON with a descriptive message:
error response
{
"status": "error",
"message": "Description of what went wrong."
}
Common Errors
| Error | Cause | Fix |
|---|---|---|
Provided domain is invalid. |
Domain format is wrong | Use a valid domain like example.com |
Scan limit reached. |
Rate limit exceeded | Wait or upgrade your plan |
Please provide all required information. |
Missing required fields in request body | Check the endpoint documentation for required fields |