{"openapi":"3.1.0","info":{"title":"MacLocalModels Compatibility API","version":"1.0.0","description":"Licensed, evidence-scoped compatibility decisions for local AI models on Apple Silicon Macs. Model weights remain at their canonical publisher or Hugging Face source.","termsOfService":"https://maclocalmodels.com/agents.txt","contact":{"name":"MacLocalModels support and licensing","email":"maclocalmodels-support@agentmail.to","url":"https://maclocalmodels.com/data"}},"servers":[{"url":"https://maclocalmodels.com","description":"Canonical production API"}],"tags":[{"name":"Compatibility","description":"Read-only Apple Silicon model-fit decisions"}],"paths":{"/api/v1/compatibility":{"get":{"operationId":"rankMacModelCompatibility","tags":["Compatibility"],"summary":"Rank compatible local AI models for a Mac memory tier and workload","description":"Returns deterministic compatibility decisions with evidence boundaries. An active MacLocalModels API key is required. Live purchasing is not active while commerce remains sandbox-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"memory","in":"query","required":true,"schema":{"type":"integer","minimum":8,"maximum":512},"example":24,"description":"Apple Silicon unified memory in GB."},{"name":"workload","in":"query","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/Workload"}],"default":"general_assistant"},"example":"coding","description":"Defaults to general_assistant when omitted."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"example":5}],"responses":{"200":{"description":"Ranked evidence-scoped compatibility decisions","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Monthly request quota."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current UTC month."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mlm_ API key","description":"MacLocalModels API key from an active licensed data plan."}},"schemas":{"Workload":{"type":"string","enum":["coding","research","writing","agents","rag","image_generation","multimodal","general_assistant"]},"ModelIdentity":{"type":"object","required":["slug","title","creator","canonicalUrl","recommendedFiles"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"creator":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"runtimeFormat":{"type":["string","null"]},"parameterCountBillions":{"type":["number","null"]},"quantization":{"type":["string","null"]},"recommendedFiles":{"type":"array","items":{"type":"string"}}}},"CompatibilityResult":{"type":"object","required":["model","fit"],"properties":{"model":{"$ref":"#/components/schemas/ModelIdentity"},"fit":{"type":"object","required":["status","confidence","summary","limitations","evidence"],"properties":{"status":{"type":"string","enum":["EXCELLENT","GOOD","POSSIBLE_WITH_TRADEOFFS","NOT_RECOMMENDED","INSUFFICIENT_EVIDENCE"]},"confidence":{"type":"string","enum":["high","medium","low"]},"summary":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","required":["type","source","url","retrievedAt"],"properties":{"type":{"type":"string","enum":["VERIFIED","MEASURED","REPORTED","ESTIMATED","UNKNOWN"]},"source":{"type":"string"},"url":{"type":"string","format":"uri"},"retrievedAt":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}}}}}}}},"CompatibilityResponse":{"type":"object","required":["data","query","evidenceBoundary","usage"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompatibilityResult"}},"query":{"type":"object","required":["memoryGb","workload","limit"],"properties":{"memoryGb":{"type":"integer"},"workload":{"$ref":"#/components/schemas/Workload"},"limit":{"type":"integer"}}},"evidenceBoundary":{"type":"string"},"usage":{"type":"object","required":["used","quota","remaining","period"],"properties":{"used":{"type":"integer"},"quota":{"type":"integer"},"remaining":{"type":"integer"},"period":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}}},"example":{"data":[{"model":{"slug":"qwen2-5-3b-instruct","title":"Qwen2.5 3B Instruct","creator":"Qwen","canonicalUrl":"https://huggingface.co/Qwen/Qwen2.5-3B-Instruct","runtimeFormat":"transformers","parameterCountBillions":3,"quantization":null,"recommendedFiles":[]},"fit":{"status":"GOOD","confidence":"medium","summary":"Fits with practical headroom; verify the exact runtime and context before sustained use.","limitations":["Estimated memory requirement remains below the selected unified-memory tier."],"evidence":[{"type":"ESTIMATED","source":"Canonical model source","url":"https://huggingface.co/Qwen/Qwen2.5-3B-Instruct","retrievedAt":"2026-09-14T00:00:00.000Z"}]}}],"query":{"memoryGb":24,"workload":"coding","limit":5},"evidenceBoundary":"Compatibility can include estimates. Follow each evidence URL and model page before operational use.","usage":{"used":1,"quota":2500,"remaining":2499,"period":"2026-09"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"pricing":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}}}},"responses":{"InvalidRequest":{"description":"Invalid memory, workload, or limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"A valid active API key is required. Current Checkout is sandbox-only and cannot activate live access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","reason":"missing_api_key","message":"Bulk and automated compatibility access requires a paid API key.","pricing":"https://maclocalmodels.com/data","documentation":"https://maclocalmodels.com/openapi.json"}}}},"QuotaExceeded":{"description":"Monthly quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"externalDocs":{"description":"Capabilities, access boundaries, and evidence states","url":"https://maclocalmodels.com/capabilities.json"}}