Developers

API reference

The exact contract implemented by the coordinator, generated from its OpenAPI document.

The API is not deployed yet. The coordinator and the contract below are tested in this repository. These URLs start answering only after the app host is configured and deployed.

Contract and limits

Version 1.0.0. Strict MAC parsing, classification, derivation and IEEE registrant lookup over a committed snapshot. Keyless with a daily credit allowance; see GET /api/v1/limits. The JSON document is served at https://macaddress.app/api/openapi.json when the API is deployed, and interactive documentation at https://macaddress.app/api/docs.

Requests use https://macaddress.app/api/v1 as the canonical prefix, except for the health route. MAC lookup and vendor search cost one credit, Bulk MAC costs one per unique address, dataset metadata costs one, and limits and health are free. GET /api/v1/limits reports the current allowance. A 429 response includes Retry-After. The current limits are held in memory per API process.

Implemented operations

Method	Path	Operation	Responses
`GET`	`/api/v1/datasets/current`	Describe the current IEEE snapshotContent version (the first 12 hex digits of a SHA-256 over the snapshot lines, the same value the site's shards are published under), generation time, per-registry counts and the paths of the static download files. Costs 1 credit. Cached for five minutes.	`200, 304, 400, 422, 429`
`GET`	`/api/v1/dns/compare`	Compare DNS answers from eight resolversAsks the local system resolver and seven public resolvers from this app host. Groups equivalent answers while reporting errors and TTLs separately. This is one vantage point, not a global propagation map. Costs 5 credits.	`200, 400, 422`
`GET`	`/api/v1/dns/lookup`	Look up a DNS record from one resolverQueries A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, PTR, SRV, HTTPS, SVCB, TLSA, DS, DNSKEY, NAPTR or SSHFP. Choose the local system resolver, Cloudflare, Google, Quad9, OpenDNS, AdGuard unfiltered, Control D unfiltered, DNS.WATCH or a public authoritative server. Reports TTLs, DNSSEC authenticated-data flag and distinct DNS outcomes from this server vantage point. Costs 2 credits.	`200, 400, 422, 503`
`GET`	`/api/v1/limits`	Show the caller's remaining allowanceRemaining daily credits, the per-second request rate, when the daily window resets and whether the identity came from the socket peer or a trusted proxy header. Free; never cached. The identity itself is never returned.	`200, 429`
`POST`	`/api/v1/mac/bulk`	Extract and look up every address in text or a listWith `text`, finds every MAC address and EUI-64 the way the browser bulk tool does (anchored formats with word boundaries; IPv4, IPv6, hashes, timestamps and hex words never match). With `addresses`, parses each entry strictly and lists the ones that fail under `rejected`. Addresses are deduplicated; up to 1,000 unique addresses per request and a 1 MiB body. Costs 1 credit per unique address. Never cached.	`200, 400, 413, 422, 429`
`GET`	`/api/v1/mac/{address}`	Look up one MAC address, EUI-64 or IEEE prefixParses the address strictly (colon, hyphen, Cisco dotted, bare, space separated, EUI-64, IEEE prefix forms and `<address>/24\|28\|36`), reports which format matched, classifies the first octet, derives EUI-64 and IPv6 forms, and returns the most specific IEEE assignment covering it or `assignment: null`. Costs 1 credit. Cached for an hour with an ETag.	`200, 304, 400, 422, 429`
`POST`	`/api/v1/measurements`	Add anonymous aggregate tool countersAccepts only recent UTC day, available local tool ID, event kind and bounded count. The body contains no input, target, token or visitor identifier. Costs no daily credit but uses the per-second request limit. Stored as aggregate SQLite bins.	`204, 422`
`GET`	`/api/v1/vendors`	Search registrant namesCase-insensitive substring search over every registrant name in the snapshot. Names that start with the query rank first, then the rest alphabetically. `limit` is capped at 100. Costs 1 credit.	`200, 400, 422, 429`
`GET`	`/healthz`	LivenessReturns ok once the dataset is loaded. Not rate limited; never cached.	`200`

MAC lookup example

The response shape below is the example attached to the MacResponse schema, not a live request. Its dataset version is illustrative; GET /api/v1/datasets/current reports the active version after each refresh. An address outside a registered block still returns a normal result with assignment: null. The strict parser reports the matched input format.

{
  "address": {
    "bits": 48,
    "format": "colon",
    "hex": "0050C2123456",
    "kind": "eui48"
  },
  "assignment": {
    "company": "IEEE Registration Authority",
    "country": "US",
    "endHex": "0050C2FFFFFF",
    "prefixBits": 24,
    "startHex": "0050C2000000",
    "type": "MA-L"
  },
  "classification": {
    "broadcast": false,
    "likelyRandomized": false,
    "locallyAdministered": false,
    "multicast": false
  },
  "datasetVersion": "137c777b20c1",
  "derivations": {
    "bitReversed": "000A43482C6A",
    "eui64": "0050C2FFFE123456",
    "integer": 346852481110,
    "ipv6LinkLocal": "fe80::250:c2ff:fe12:3456",
    "modifiedEui64": "0250C2FFFE123456"
  },
  "formats": {
    "bare": "0050C2123456",
    "colon": "00:50:C2:12:34:56",
    "dot": "0050.C212.3456",
    "hyphen": "00-50-C2-12-34-56",
    "space": "00 50 C2 12 34 56"
  },
  "input": "00:50:C2:12:34:56"
}

Dataset and local tools

Download the IEEE snapshot as static JSON or CSV with checksums. Browser-local tools on this site do not require an API request. The operations table above contains only implemented coordinator routes; future remote diagnostics will join it when their contracts exist.