Developers
Public API
One JSON interface for every remote tool and the deterministic local ones, so scripts can call what the pages show.
Not yet live. This page describes the contract the API will implement. Endpoints, field names and limits below may still change before the first release; nothing here answers requests today.
Basics
- Canonical prefix
https://macaddress.app/api/v1, JSON in and out. - OpenAPI at
https://macaddress.app/api/openapi.json, interactive docs athttps://macaddress.app/api/docs. - The free tier is keyless with hard caps so scripts can embed it without onboarding. Keys, higher caps and a credit pool come later.
- Consistent error envelope with stable codes: 400 or 422 for validation, 404 for an unknown resource, 429 with
Retry-After, 503 with retry guidance. - Changes within v1 are additive. Field names match the browser modules, so a result you see on a page has the same shape from the API.
Operations
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/mac/{address} | Strict parse, classification, derivations and IEEE assignment for one address |
POST | /api/v1/mac/bulk | Extraction plus lookup, up to 1,000 unique addresses per request |
GET | /api/v1/vendors?q= | Bounded organization search |
GET | /api/v1/datasets/current | Snapshot metadata and download URLs |
POST | /api/v1/tools/{tool_id} | Typed requests for deterministic tools (subnet, cidr, encoders, hash, timestamp, cert-decode) |
GET | /api/v1/ip | The requester’s public address; never cached |
GET | /api/v1/ip/{address} | Classification plus enrichment |
GET | /api/v1/dns?name=&type=&resolver= | Bounded resolution with distinct outcomes |
GET | /api/v1/rdap?query= | RDAP with WHOIS fallback |
POST | /api/v1/email-auth | Domain scorecard |
POST | /api/v1/http | Redirect chain and headers |
POST | /api/v1/headers | Observatory grade and tests |
POST | /api/v1/tls/quick | sslyze summary |
POST | /api/v1/scans | Queue a full TLS scan; 202 with status and report links |
GET | /api/v1/scans/{token} | Scan status and result |
GET | /api/v1/scans/{token}/download | Structured evidence |
GET | /api/v1/limits | Effective limits for the caller and remaining credits |
Example
What a MAC lookup will look like once the API is live:
curl https://macaddress.app/api/v1/mac/3C:22:FB:9A:12:34A well-formed address with no registered block answers with a normal 200 and an empty assignment, with the classification still filled in; the parse itself never fails on formatting alone because the parser matches anchored formats and reports which one matched.
Credits
Each operation has a credit cost listed on its tool page. Local tools cost nothing on the site; the same operation through the API costs one credit or more because it runs on our hardware. Full TLS scans are the most expensive at 50. GET /api/v1/limits reports what a caller has left.