mlx-knife/docs/json-api-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/mlxk-json-api.schema.json",
  "title": "MLX-Knife 2.0 JSON API 0.1.7 (current)",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {"type": "string", "enum": ["success", "error"]},
    "command": {"type": "string", "enum": ["list", "show", "health", "pull", "rm", "clone", "version", "push", "run", "server"]},
    "api_version": {"type": "string", "pattern": "^json-[0-9]+\\.[0-9]+\\.[0-9]+$"},
    "data": {"type": ["object", "null"]},
    "error": {
      "type": ["object", "null"],
      "properties": {
        "type": {"type": "string"},
        "message": {"type": "string"},
        "matches": {"type": "array", "items": {"type": "string"}},
        "available_hashes": {"type": "array", "items": {"type": "string"}}
      },
      "additionalProperties": true
    }
  },
  "required": ["status", "command", "data", "error"],
  "allOf": [
    {"$ref": "#/definitions/byCommand"}
  ],
  "definitions": {
    "hash40": {"type": "string", "pattern": "^[A-Za-z0-9]{40}$"},
    "isoUtcZ": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"},
    "healthEntry": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "status": {"type": "string", "enum": ["healthy", "unhealthy"]},
        "reason": {"type": "string"}
      },
      "required": ["name", "status", "reason"],
      "additionalProperties": false
    },
    "modelObject": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {"type": "string"},
        "hash": {"anyOf": [{"$ref": "#/definitions/hash40"}, {"type": "null"}]},
        "size_bytes": {"type": "integer", "minimum": 0},
        "last_modified": {"$ref": "#/definitions/isoUtcZ"},
        "framework": {"type": "string", "enum": ["MLX", "GGUF", "PyTorch", "Unknown"]},
        "model_type": {"type": "string", "description": "Model type classification. See mlxk2/core/capabilities.py for currently detected values."},
        "capabilities": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Model capabilities. Values are not normative - see mlxk2/core/capabilities.py Capability enum for currently detected values."
        },
        "health": {"type": "string", "enum": ["healthy", "unhealthy"]},
        "runtime_compatible": {"type": "boolean"},
        "reason": {"type": ["string", "null"]},
        "cached": {"type": "boolean"}
      },
      "required": [
        "name", "hash", "size_bytes", "last_modified", "framework",
        "model_type", "capabilities", "health", "runtime_compatible", "cached"
      ],
      "description": "Extended in 0.1.5: added runtime_compatible (boolean) and reason (string|null) fields. Both checks always performed in JSON mode. reason describes the first problem found (integrity or runtime). Gate logic: runtime check requires integrity check first. CLI flags (--health, --runtime-check) control human output columns only, not JSON data collection."
    },
    "fileEntry": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {"type": "string"},
        "size": {"type": "string"},
        "type": {"type": "string"}
      },
      "required": ["name", "size", "type"]
    },
    "systemObject": {
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "memory_total_bytes": {"type": "integer", "minimum": 0}
      },
      "description": "System information (0.1.6+). null if unavailable (non-macOS platforms). memory_total_bytes: Total physical RAM in bytes from sysctl hw.memsize."
    },
    "byCommand": {
      "allOf": [
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "version"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "cli_version": {"type": "string"},
                  "json_api_spec_version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
                  "system": {"$ref": "#/definitions/systemObject"}
                },
                "required": ["cli_version", "json_api_spec_version"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "list"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "models": {"type": "array", "items": {"$ref": "#/definitions/modelObject"}},
                  "count": {"type": "integer", "minimum": 0}
                },
                "required": ["models", "count"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "show"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "model": {"$ref": "#/definitions/modelObject"},
                  "metadata": {"type": ["object", "null"]},
                  "files": {"type": "array", "items": {"$ref": "#/definitions/fileEntry"}},
                  "config": {"type": ["object", "null"]}
                },
                "required": ["model"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "health"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "healthy": {
                    "type": "array",
                    "items": {"$ref": "#/definitions/healthEntry"}
                  },
                  "unhealthy": {
                    "type": "array",
                    "items": {"$ref": "#/definitions/healthEntry"}
                  },
                  "summary": {
                    "type": "object",
                    "properties": {
                      "total": {"type": "integer", "minimum": 0},
                      "healthy_count": {"type": "integer", "minimum": 0},
                      "unhealthy_count": {"type": "integer", "minimum": 0}
                    },
                    "required": ["total", "healthy_count", "unhealthy_count"],
                    "additionalProperties": false
                  }
                },
                "required": ["healthy", "unhealthy", "summary"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "pull"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "model": {"type": ["string", "null"]},
                  "download_status": {"type": "string"},
                  "message": {"type": "string"},
                  "expanded_name": {"type": ["string", "null"]}
                },
                "required": ["download_status", "message"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "rm"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "model": {"type": ["string", "null"]},
                  "action": {"type": "string"},
                  "message": {"type": "string"}
                },
                "required": ["action"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "push"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {"type": "string"},
                  "branch": {"type": "string"},
                  "commit_sha": {"type": ["string", "null"]},
                  "repo_url": {"type": "string"},
                  "uploaded_files_count": {"type": ["integer", "null"], "minimum": 0},
                  "experimental": {"type": "boolean"},
                  "disclaimer": {"type": "string"}
                },
                "required": ["repo_id", "branch", "repo_url"]
              }
            }
          },
          "else": {}
        },
        {
          "if": {
            "allOf": [
              {"properties": {"status": {"const": "success"}}},
              {"properties": {"command": {"const": "run"}}}
            ]
          },
          "then": {
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "model": {"type": "string"},
                  "prompt": {"type": "string"},
                  "response": {"type": "string"},
                  "tokens_generated": {"type": "integer"},
                  "generation_time_s": {"type": "number"}
                }
              }
            }
          },
          "else": {}
        }
      ]
    }
  }
}