{ "openapi": "3.1.0", "info": { "title": "QuantTrail API", "version": "1.0.0", "description": "QuantTrail, the Local AI Model Finder by NorthPanda Labs. Deterministic local model recommendations (the QuantTrail Picker). Requests and hardware are not stored, except computers an account holder chooses to save (/v1/me/presets) and the phone and board survey (store_device: model name, RAM and class, opt out per call). Applications of the operator authenticate with X-QuantTrail-Key." }, "servers": [ { "url": "/" } ], "paths": { "/v1/recommend": { "post": { "summary": "Rank local models using hardware and preferences", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "hardware" ], "properties": { "hardware": { "type": "object", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" }, "platform": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] }, "ram_gb": { "type": "number", "minimum": 1, "maximum": 2048 }, "cpu_cores": { "type": "integer", "minimum": 1, "maximum": 512 }, "gpu_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "gpu": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" }, "vram_gb": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 }, "disk_free_gb": { "type": "number", "minimum": 0, "maximum": 100000 }, "memory_bandwidth_gbps": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." }, "device_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." }, "chip": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." }, "memory_type": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] }, "memory_speed_mts": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." }, "memory_bus_bits": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, "anyOf": [ { "required": [ "tier" ] }, { "required": [ "platform", "ram_gb" ] }, { "required": [ "device_model" ] } ] }, "preferences": { "type": "object", "additionalProperties": false, "properties": { "smartness_min": { "type": "number", "minimum": 1, "maximum": 10, "default": 1 }, "size_max_gb": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "priority": { "type": "string", "enum": [ "balanced", "quality", "speed", "small" ], "default": "balanced" }, "min_speed": { "type": "string", "enum": [ "fast", "moderate", "slow", "very_slow" ], "default": "slow" }, "tasks": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [ "chat" ], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 }, "origins": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "families_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "families_exclude": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "family_kind": { "type": "string", "enum": [ "any", "brand", "specialized" ], "default": "any", "description": "brand keeps the general-purpose families that work across subjects (Gemma, Qwen, Llama); specialized keeps the families built for one job or one size band (code completion, small devices). Each family in /v1/families carries its kind." }, "vendors_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "vendors_exclude": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "license": { "type": "string", "enum": [ "any", "permissive" ], "default": "any" }, "allow_gated": { "type": "boolean", "default": true }, "quant_min": { "type": "string", "default": "Q4_K_M", "description": "Tracked minimum format ID; order comes from /v1/formats. This is not an exact-format allowlist; use quants for that." }, "support_levels": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Support levels to include, by id from /v1/meta support_levels (for example [\"current\",\"limited_1\"]). Empty means every level. Each model and recommendation carries support {id,label,limited}: models released before a cut-off are Limited, newer ones Current." }, "quants": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Exact formats to consider: any tracked or known format ID from /v1/formats, for example [\"Q4_K_M\",\"Q6_K\",\"Q4_K_S\"]. When given, only these are used and quant_min is ignored. Known formats are measured where the crawler saw the file and otherwise estimated (size_source), and may be missing from the GGUF repository." } } }, "candidates": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "include_cpu": { "type": "boolean", "default": true }, "detected": { "type": "array", "items": { "type": "string", "enum": [ "platform", "cpu_cores", "ram_gb", "gpu" ] }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5 }, "install": { "type": "boolean", "default": false, "description": "Add an install block to each recommendation (see /v1/picks)." }, "store_device": { "type": "boolean", "default": true, "description": "Phone and board survey. When hardware.device_model is sent for a phone, tablet or board, its name as sent, the RAM and the class are saved for the operator to review, at most three per client session, and the response carries survey.message. Send false on each call to opt out. No chip, memory speed, bandwidth or address is kept, and desktops are never recorded." } } }, "example": { "hardware": { "tier": "high" }, "preferences": { "tasks": [ "chat" ], "context_tokens": 8192 }, "limit": 5 } } } } }, "get": { "summary": "Equivalent flat-query recommendation", "parameters": [ { "name": "tier", "in": "query", "schema": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" } }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] } }, { "name": "ram_gb", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 2048 } }, { "name": "cpu_cores", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512 } }, { "name": "gpu_name", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "gpu", "in": "query", "schema": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" } }, { "name": "vram_gb", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 } }, { "name": "disk_free_gb", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "memory_bandwidth_gbps", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." } }, { "name": "device_model", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." } }, { "name": "chip", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." } }, { "name": "memory_type", "in": "query", "schema": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] } }, { "name": "memory_speed_mts", "in": "query", "schema": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." } }, { "name": "memory_bus_bits", "in": "query", "schema": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, { "name": "smartness_min", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "size_max_gb", "in": "query", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "balanced", "quality", "speed", "small" ], "default": "balanced" } }, { "name": "min_speed", "in": "query", "schema": { "type": "string", "enum": [ "fast", "moderate", "slow", "very_slow" ], "default": "slow" } }, { "name": "tasks", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [ "chat" ], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "context_tokens", "in": "query", "schema": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 } }, { "name": "origins", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "families_include", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "families_exclude", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "family_kind", "in": "query", "schema": { "type": "string", "enum": [ "any", "brand", "specialized" ], "default": "any", "description": "brand keeps the general-purpose families that work across subjects (Gemma, Qwen, Llama); specialized keeps the families built for one job or one size band (code completion, small devices). Each family in /v1/families carries its kind." } }, { "name": "vendors_include", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "vendors_exclude", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "license", "in": "query", "schema": { "type": "string", "enum": [ "any", "permissive" ], "default": "any" } }, { "name": "allow_gated", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "quant_min", "in": "query", "schema": { "type": "string", "default": "Q4_K_M", "description": "Tracked minimum format ID; order comes from /v1/formats. This is not an exact-format allowlist; use quants for that." } }, { "name": "support_levels", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Support levels to include, by id from /v1/meta support_levels (for example [\"current\",\"limited_1\"]). Empty means every level. Each model and recommendation carries support {id,label,limited}: models released before a cut-off are Limited, newer ones Current." }, "style": "form", "explode": false }, { "name": "quants", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Exact formats to consider: any tracked or known format ID from /v1/formats, for example [\"Q4_K_M\",\"Q6_K\",\"Q4_K_S\"]. When given, only these are used and quant_min is ignored. Known formats are measured where the crawler saw the file and otherwise estimated (size_source), and may be missing from the GGUF repository." }, "style": "form", "explode": false }, { "name": "candidates", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "include_cpu", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "detected", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "platform", "cpu_cores", "ram_gb", "gpu" ] }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "style": "form", "explode": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5 } }, { "name": "install", "in": "query", "schema": { "type": "boolean", "default": false, "description": "Add an install block to each recommendation (see /v1/picks)." } }, { "name": "store_device", "in": "query", "schema": { "type": "boolean", "default": true, "description": "Phone and board survey. When hardware.device_model is sent for a phone, tablet or board, its name as sent, the RAM and the class are saved for the operator to review, at most three per client session, and the response carries survey.message. Send false on each call to opt out. No chip, memory speed, bandwidth or address is kept, and desktops are never recorded." } } ], "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" } } } }, "/v1/picks": { "post": { "summary": "Top picks for one use (coding, chat, dnd_dm): reasoning and speed lists with the context that fits", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "hardware", "use" ], "properties": { "hardware": { "type": "object", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" }, "platform": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] }, "ram_gb": { "type": "number", "minimum": 1, "maximum": 2048 }, "cpu_cores": { "type": "integer", "minimum": 1, "maximum": 512 }, "gpu_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "gpu": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" }, "vram_gb": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 }, "disk_free_gb": { "type": "number", "minimum": 0, "maximum": 100000 }, "memory_bandwidth_gbps": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." }, "device_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." }, "chip": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." }, "memory_type": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] }, "memory_speed_mts": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." }, "memory_bus_bits": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, "anyOf": [ { "required": [ "tier" ] }, { "required": [ "platform", "ram_gb" ] }, { "required": [ "device_model" ] } ] }, "use": { "type": "string", "description": "Use profile: coding, chat or dnd_dm by default; the operator can add more in /admin/site (settings pick_profile_)." }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "description": "Context length to plan for; defaults to the profile (coding 16384, chat 8192, dnd_dm 16384). Memory estimates and max_context_tokens follow it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "install": { "type": "boolean", "default": false, "description": "Add an install block to each pick: name, Ollama tag with pull/run commands and library URL, Hugging Face repo URL, and the GGUF repo, file, direct file URL, hf download and curl commands." }, "store_device": { "type": "boolean", "default": true, "description": "Same phone and board survey as /v1/recommend." } } } } } } }, "get": { "summary": "Equivalent flat-query picks", "parameters": [ { "name": "tier", "in": "query", "schema": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" } }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] } }, { "name": "ram_gb", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 2048 } }, { "name": "cpu_cores", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512 } }, { "name": "gpu_name", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "gpu", "in": "query", "schema": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" } }, { "name": "vram_gb", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 } }, { "name": "disk_free_gb", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "memory_bandwidth_gbps", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." } }, { "name": "device_model", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." } }, { "name": "chip", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." } }, { "name": "memory_type", "in": "query", "schema": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] } }, { "name": "memory_speed_mts", "in": "query", "schema": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." } }, { "name": "memory_bus_bits", "in": "query", "schema": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, { "name": "use", "in": "query", "schema": { "type": "string", "description": "Use profile: coding, chat or dnd_dm by default; the operator can add more in /admin/site (settings pick_profile_)." } }, { "name": "context_tokens", "in": "query", "schema": { "type": "integer", "minimum": 512, "maximum": 2000000, "description": "Context length to plan for; defaults to the profile (coding 16384, chat 8192, dnd_dm 16384). Memory estimates and max_context_tokens follow it." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } }, { "name": "install", "in": "query", "schema": { "type": "boolean", "default": false, "description": "Add an install block to each pick: name, Ollama tag with pull/run commands and library URL, Hugging Face repo URL, and the GGUF repo, file, direct file URL, hf download and curl commands." } }, { "name": "store_device", "in": "query", "schema": { "type": "boolean", "default": true, "description": "Same phone and board survey as /v1/recommend." } } ], "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" } } } }, "/v1/requirements": { "post": { "summary": "Find the required hardware for models or preferences", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "models": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "preferences": { "type": "object", "additionalProperties": false, "properties": { "smartness_min": { "type": "number", "minimum": 1, "maximum": 10, "default": 1 }, "size_max_gb": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "priority": { "type": "string", "enum": [ "balanced", "quality", "speed", "small" ], "default": "balanced" }, "min_speed": { "type": "string", "enum": [ "fast", "moderate", "slow", "very_slow" ], "default": "slow" }, "tasks": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [ "chat" ], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 }, "origins": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "families_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "families_exclude": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "family_kind": { "type": "string", "enum": [ "any", "brand", "specialized" ], "default": "any", "description": "brand keeps the general-purpose families that work across subjects (Gemma, Qwen, Llama); specialized keeps the families built for one job or one size band (code completion, small devices). Each family in /v1/families carries its kind." }, "vendors_include": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "vendors_exclude": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Validated against the catalog. Empty include lists mean unrestricted." }, "license": { "type": "string", "enum": [ "any", "permissive" ], "default": "any" }, "allow_gated": { "type": "boolean", "default": true }, "quant_min": { "type": "string", "default": "Q4_K_M", "description": "Tracked minimum format ID; order comes from /v1/formats. This is not an exact-format allowlist; use quants for that." }, "support_levels": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Support levels to include, by id from /v1/meta support_levels (for example [\"current\",\"limited_1\"]). Empty means every level. Each model and recommendation carries support {id,label,limited}: models released before a cut-off are Limited, newer ones Current." }, "quants": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200, "default": [], "description": "Exact formats to consider: any tracked or known format ID from /v1/formats, for example [\"Q4_K_M\",\"Q6_K\",\"Q4_K_S\"]. When given, only these are used and quant_min is ignored. Known formats are measured where the crawler saw the file and otherwise estimated (size_source), and may be missing from the GGUF repository." } } }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5 } }, "oneOf": [ { "required": [ "models" ], "not": { "required": [ "preferences" ] } }, { "required": [ "preferences" ], "not": { "required": [ "models" ] } } ] } } } } } }, "/v1/models": { "get": { "summary": "List catalog models and variants", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "parameters": [ { "name": "family", "in": "query", "schema": { "type": "string" } }, { "name": "generation", "in": "query", "schema": { "type": "string" } }, { "name": "vendor", "in": "query", "schema": { "type": "string" } }, { "name": "origin", "in": "query", "schema": { "type": "string" } }, { "name": "task", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "include_retired", "in": "query", "schema": { "type": "string" } } ] } }, "/v1/models/{id}": { "get": { "summary": "Get one non-hidden model with research links", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/models/{id}/fit": { "post": { "summary": "One model on given hardware: every format with memory, where it runs, speed and the context that fits", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "hardware" ], "properties": { "hardware": { "type": "object", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" }, "platform": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] }, "ram_gb": { "type": "number", "minimum": 1, "maximum": 2048 }, "cpu_cores": { "type": "integer", "minimum": 1, "maximum": 512 }, "gpu_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "gpu": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" }, "vram_gb": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 }, "disk_free_gb": { "type": "number", "minimum": 0, "maximum": 100000 }, "memory_bandwidth_gbps": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." }, "device_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." }, "chip": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." }, "memory_type": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] }, "memory_speed_mts": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." }, "memory_bus_bits": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, "anyOf": [ { "required": [ "tier" ] }, { "required": [ "platform", "ram_gb" ] }, { "required": [ "device_model" ] } ] }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/models/{id}/votes": { "get": { "summary": "Vote counts per hardware class; with a session token also the caller's own vote", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found" } } }, "post": { "summary": "Cast or change the signed-in account's vote (Authorization: Bearer ); one vote per account per model", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required: no valid session, or the email is not confirmed" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "value", "tier" ], "properties": { "value": { "type": "string", "enum": [ "up", "down" ] }, "tier": { "type": "string", "description": "Hardware class ID from /v1/hardware/tiers. Only this class is saved with the vote." } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/me/presets": { "get": { "summary": "List saved computers", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "sign_in_required" }, "404": { "description": "Not found" }, "409": { "description": "preset_limit (10 per account)" } } }, "post": { "summary": "Save a computer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 60 }, "hardware": { "type": "object", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" }, "platform": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] }, "ram_gb": { "type": "number", "minimum": 1, "maximum": 2048 }, "cpu_cores": { "type": "integer", "minimum": 1, "maximum": 512 }, "gpu_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "gpu": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" }, "vram_gb": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 }, "disk_free_gb": { "type": "number", "minimum": 0, "maximum": 100000 }, "memory_bandwidth_gbps": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." }, "device_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." }, "chip": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." }, "memory_type": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] }, "memory_speed_mts": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." }, "memory_bus_bits": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, "anyOf": [ { "required": [ "tier" ] }, { "required": [ "platform", "ram_gb" ] }, { "required": [ "device_model" ] } ] }, "task": { "type": "string", "default": "chat" }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 } }, "required": [ "name", "hardware" ] } } } }, "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "sign_in_required" }, "404": { "description": "Not found" }, "409": { "description": "preset_limit (10 per account)" } } } }, "/v1/me/watches": { "get": { "summary": "Model families the signed-in account follows and the models new in them since it last looked: GET lists, POST {\"family\"} follows, POST /v1/me/watches/seen marks all as seen, POST /v1/me/watches/{family}/remove stops following", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/me/presets/{id}": { "get": { "summary": "Read one saved computer", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "sign_in_required" }, "404": { "description": "Not found" }, "409": { "description": "preset_limit (10 per account)" } } }, "post": { "summary": "Rename or change a saved computer", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 60 }, "hardware": { "type": "object", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "Current tier ID from /v1/hardware/tiers" }, "platform": { "type": "string", "enum": [ "windows", "macos", "linux", "android", "ios" ] }, "ram_gb": { "type": "number", "minimum": 1, "maximum": 2048 }, "cpu_cores": { "type": "integer", "minimum": 1, "maximum": 512 }, "gpu_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "gpu": { "type": "string", "enum": [ "none", "integrated", "nvidia", "amd", "intel", "apple", "unified" ], "default": "none" }, "vram_gb": { "type": "number", "minimum": 0, "maximum": 1024, "default": 0 }, "disk_free_gb": { "type": "number", "minimum": 0, "maximum": 100000 }, "memory_bandwidth_gbps": { "type": "number", "minimum": 1, "maximum": 2000, "description": "System memory bandwidth in GB/s, from /v1/hardware/devices or entered by hand. Enables a tokens-per-second estimate for CPU and phone fits. Takes precedence over every value below." }, "device_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Device name or model code, for example Galaxy S24 or SM-S921B. A device in /v1/hardware/devices fills platform, RAM, cores and bandwidth that were not sent." }, "chip": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chip name, for example Snapdragon 8 Gen 3. A chip in /v1/hardware/chips fills cores and bandwidth that were not sent." }, "memory_type": { "type": "string", "enum": [ "ddr3", "ddr4", "ddr5", "lpddr3", "lpddr4", "lpddr4x", "lpddr5", "lpddr5x" ] }, "memory_speed_mts": { "type": "number", "minimum": 400, "maximum": 20000, "description": "Memory transfer rate in MT/s, for example 8533. With memory_type, bandwidth is worked out when no device or chip supplied it; a typical speed is assumed when missing." }, "memory_bus_bits": { "type": "integer", "minimum": 16, "maximum": 1024, "description": "Memory bus width in bits. Assumed 64 for LPDDR (and phones), 128 for DDR (two channels)." } }, "anyOf": [ { "required": [ "tier" ] }, { "required": [ "platform", "ram_gb" ] }, { "required": [ "device_model" ] } ] }, "task": { "type": "string", "default": "chat" }, "context_tokens": { "type": "integer", "minimum": 512, "maximum": 2000000, "default": 8192 } } } } } }, "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "sign_in_required" }, "404": { "description": "Not found" }, "409": { "description": "preset_limit (10 per account)" } } } }, "/v1/top-models": { "get": { "summary": "The strongest models for five size classes (phone to 128 GB) for chat and coding, ranked as a search would, with Hugging Face links; the Top models page", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/highlights": { "get": { "summary": "Most recently released models mixed with the most downloaded (last 30 days), for the strip at the top of the site", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/plans": { "get": { "summary": "The account levels: prices, API keys, weekly requests and model families per key", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/me": { "get": { "summary": "The signed-in account (Authorization: Bearer session token): level, requests this week and its API keys. Keys are managed at /v1/me/keys", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/families": { "get": { "summary": "List model families", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/vendors": { "get": { "summary": "List companies and origins", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/hardware/gpus": { "get": { "summary": "Resolve a renderer or autocomplete GPU names", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "renderer", "in": "query", "schema": { "type": "string" } } ] } }, "/v1/hardware/devices": { "get": { "summary": "List phones, tablets and ARM boards; match an Android model or board renderer", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string" } }, { "name": "renderer", "in": "query", "schema": { "type": "string" } } ] } }, "/v1/hardware/chips": { "get": { "summary": "List phone and board chips with memory bandwidth; match a chip name", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ] } }, "/v1/hardware/tiers": { "get": { "summary": "Read editable hardware tiers", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/formats": { "get": { "summary": "Explain tracked and known formats", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/site": { "get": { "summary": "Read donation links and site message", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/survey": { "get": { "summary": "Most recommended models per phone and board class from the survey; no counts, names or RAM", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/meta": { "get": { "summary": "Read freshness, option enums and voting configuration", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } } } }, "/v1/votes": { "post": { "summary": "Retired 2026-10-10: answers 410 gone. Vote with an account at POST /v1/models/{id}/votes", "responses": { "200": { "description": "JSON response. Recommendation and catalog data may be empty until the first successful crawl.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "sign_in_required or invalid_key" }, "403": { "description": "quota_exhausted, or the request is refused" }, "404": { "description": "Not found" }, "405": { "description": "Method not allowed" }, "410": { "description": "Retired route" }, "413": { "description": "Body exceeds 16384 bytes" }, "415": { "description": "JSON required" }, "429": { "description": "rate_limited (see Retry-After) or vote_locked" }, "503": { "description": "Voting switched off" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } } }