{
  "openapi": "3.1.1",
  "info": {
    "title": "macvendor API",
    "version": "1.0.0",
    "description": "Source-aware MAC address block assignment lookup. Synthetic examples only; an assignment is not proof of a physical device manufacturer."
  },
  "servers": [
    { "url": "https://macvendor.io", "description": "Maintained public service" }
  ],
  "paths": {
    "/v1/lookup/{mac}": {
      "get": {
        "operationId": "lookupMac",
        "description": "Returns the longest active official match by probing 36, 28, then 24 bits. A successful miss is HTTP 200 with matchStatus=no_match, assignment=null, and release metadata.",
        "parameters": [
          { "name": "mac", "in": "path", "required": true, "schema": { "type": "string" }, "example": "02AABBCC0001" },
          { "name": "mode", "in": "query", "description": "enriched returns separate assignment, curatedMatches, and insights layers. all is a deprecated compatibility alias for enriched.", "schema": { "type": "string", "enum": ["enriched", "official", "all"], "default": "enriched" } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/LookupSuccess" },
          "308": { "$ref": "#/components/responses/CanonicalRedirect" },
          "400": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/lookups": {
      "post": {
        "operationId": "bulkLookupMacs",
        "description": "Bulk lookup for up to 100 official or 50 enriched MAC addresses. Official mode is the backward-compatible default. Official cost is one unit per two submitted entries rounded up; enriched cost is one unit per submitted entry.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "oneOf": [
            { "type": "object", "additionalProperties": false, "required": ["macs"], "properties": { "mode": { "const": "official", "default": "official" }, "macs": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } } },
            { "type": "object", "additionalProperties": false, "required": ["mode", "macs"], "properties": { "mode": { "const": "enriched" }, "macs": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" } } } }
          ] } } }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/BulkLookupSuccess" },
          "400": { "$ref": "#/components/responses/Problem" },
          "413": { "$ref": "#/components/responses/Problem" },
          "415": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/assignments/{registry}/{prefix}": {
      "get": {
        "operationId": "getAssignment",
        "parameters": [
          { "name": "registry", "in": "path", "required": true, "schema": { "type": "string", "enum": ["ma-l", "ma-m", "ma-s", "iab", "cid"] }, "example": "ma-l" },
          { "name": "prefix", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-F]+-(24|28|36)$" }, "example": "02AABB-24" },
          { "name": "include", "in": "query", "schema": { "type": "string", "const": "evidence" } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/AssignmentSuccess" },
          "308": { "$ref": "#/components/responses/CanonicalRedirect" },
          "400": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/data-release": {
      "get": {
        "operationId": "getDataRelease",
        "responses": {
          "200": { "$ref": "#/components/responses/DataReleaseSuccess" },
          "400": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/data-release/changes": {
      "get": {
        "operationId": "getDataReleaseChanges",
        "description": "Aggregate difference between the active and preceding governed releases; raw source rows are not returned.",
        "responses": {
          "200": { "$ref": "#/components/responses/ReleaseChangesSuccess" },
          "400": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/organizations": {
      "get": {
        "operationId": "searchOrganizations",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } },
          { "name": "scheme", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$" } },
          { "name": "registry", "in": "query", "schema": { "type": "string", "enum": ["MA-L", "MA-M", "MA-S", "IAB"] } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/OrganizationSearchSuccess" },
          "400": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/organizations/{key}": {
      "get": {
        "operationId": "getOrganization",
        "parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:._-]{1,80}$" } }],
        "responses": {
          "200": { "$ref": "#/components/responses/OrganizationSuccess" },
          "400": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/corrections": {
      "post": {
        "operationId": "submitCorrection",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/CorrectionRequest" } } } },
        "responses": {
          "202": { "$ref": "#/components/responses/CorrectionAccepted" },
          "400": { "$ref": "#/components/responses/Problem" },
          "413": { "$ref": "#/components/responses/Problem" },
          "415": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RequestId": { "description": "Opaque request identifier", "schema": { "type": "string" } },
      "ApiVersion": { "description": "Stable public API contract version", "schema": { "type": "string", "const": "v1" } },
      "AppVersion": { "description": "Deployed application SemVer", "schema": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" } },
      "CacheControl": { "description": "Representation cache policy", "schema": { "type": "string" } },
      "ETag": { "description": "Opaque representation validator for cacheable GET responses; compression proxies may expose a weak encoded variant", "schema": { "type": "string" } },
      "Location": { "description": "Canonical URL", "schema": { "type": "string", "format": "uri" } },
      "RetryAfter": { "description": "Seconds before retry", "schema": { "type": "integer", "minimum": 1 } }
    },
    "responses": {
      "LookupSuccess": {
        "description": "Lookup result; no match is still a successful response",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/LookupResponse" } } }
      },
      "BulkLookupSuccess": {
        "description": "Bounded official or enriched bulk lookup result",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/BulkLookupResponse" } } }
      },
      "AssignmentSuccess": {
        "description": "Exact active assignment",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/AssignmentResponse" } } }
      },
      "DataReleaseSuccess": {
        "description": "Active release metadata",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/DataReleaseResponse" } } }
      },
      "ReleaseChangesSuccess": {
        "description": "Aggregate active release changes",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/ReleaseChangesResponse" } } }
      },
      "OrganizationSearchSuccess": {
        "description": "Reviewed organization identity search",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/OrganizationSearchResponse" } } }
      },
      "OrganizationSuccess": {
        "description": "Reviewed organization identity",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/Organization" } } }
      },
      "CorrectionAccepted": {
        "description": "Correction request durably accepted",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } },
        "content": { "application/json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/CorrectionAccepted" } } }
      },
      "CanonicalRedirect": {
        "description": "Permanent redirect to the canonical path while preserving the query",
        "headers": {
          "X-Request-Id": { "$ref": "#/components/headers/RequestId" },
          "X-API-Version": { "$ref": "#/components/headers/ApiVersion" },
          "X-App-Version": { "$ref": "#/components/headers/AppVersion" },
          "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
          "Location": { "$ref": "#/components/headers/Location" }
        }
      },
      "Problem": {
        "description": "RFC 9457 problem response",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "X-App-Version": { "$ref": "#/components/headers/AppVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } },
        "content": { "application/problem+json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/Problem" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "X-Request-Id": { "$ref": "#/components/headers/RequestId" },
          "X-API-Version": { "$ref": "#/components/headers/ApiVersion" },
          "X-App-Version": { "$ref": "#/components/headers/AppVersion" },
          "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
          "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
        },
        "content": { "application/problem+json": { "schema": { "$ref": "/schemas/public-api-v1.schema.json#/$defs/Problem" } } }
      }
    }
  }
}