{
  "name": "api.diff",
  "group": "data",
  "summary": "Diff an API's declared contract against payloads it actually returned; classify the drift.",
  "description": "Answers 'is this endpoint keeping its promise' — the failure mode where docs say one thing and the live API returns another, the schema validates, and nothing errors. Give it the declared JSON Schema (or a baseline payload to infer one from) plus one or more observed payloads. Returns a verdict, the inferred observed schema, and classified findings: type_mismatch, missing_field and enum_violation (action: block), nullable_in_practice, format_mismatch, undeclared_field and extra_field (action: warn), each with a JSON Pointer path and how many samples it affected. Declared-schema keywords outside the checked subset are listed in ignored_keywords, never silently trusted. Stateless: you hold the baseline, nothing is stored.",
  "keywords": [
    "api drift",
    "schema drift",
    "docs lie",
    "observed contract",
    "contract testing",
    "response validation",
    "openapi mismatch",
    "nullable in practice",
    "breaking change detection"
  ],
  "endpoint": "https://fluentedi.com/v1/api/diff",
  "mcp_name": "api_diff",
  "makes_network_request": false,
  "parameters": {
    "type": "object",
    "properties": {
      "declared": {
        "description": "Declared contract: a JSON Schema (object or string). Omit to infer one from `baseline`.",
        "maxLength": 500000
      },
      "baseline": {
        "description": "Alternative to `declared`: a known-good payload (or array of them) to infer the contract from.",
        "maxLength": 500000
      },
      "observed": {
        "description": "Payload the endpoint actually returned, or an array of payloads to check together.",
        "maxLength": 1000000
      },
      "samples": {
        "description": "Treat a top-level `observed` array as multiple samples rather than one array payload.",
        "type": "boolean",
        "default": true
      }
    },
    "required": [
      "observed"
    ],
    "additionalProperties": false
  },
  "examples": [
    {
      "description": "Docs promise a non-null string id and a status enum; the live API drifted",
      "url": "https://fluentedi.com/v1/api/diff?declared=%7B%22type%22%3A%22object%22%2C%22required%22%3A%5B%22id%22%2C%22status%22%5D%2C%22properties%22%3A%7B%22id%22%3A%7B%22type%22%3A%22string%22%7D%2C%22status%22%3A%7B%22enum%22%3A%5B%22active%22%2C%22closed%22%5D%7D%2C%22total%22%3A%7B%22type%22%3A%22integer%22%7D%7D%7D&observed=%5B%7B%22id%22%3A%22a1%22%2C%22status%22%3A%22active%22%2C%22total%22%3A10%7D%2C%7B%22id%22%3Anull%2C%22status%22%3A%22archived%22%2C%22total%22%3A10.5%2C%22currency%22%3A%22USD%22%7D%5D",
      "args": {
        "declared": "{\"type\":\"object\",\"required\":[\"id\",\"status\"],\"properties\":{\"id\":{\"type\":\"string\"},\"status\":{\"enum\":[\"active\",\"closed\"]},\"total\":{\"type\":\"integer\"}}}",
        "observed": "[{\"id\":\"a1\",\"status\":\"active\",\"total\":10},{\"id\":null,\"status\":\"archived\",\"total\":10.5,\"currency\":\"USD\"}]"
      }
    },
    {
      "description": "No schema? Diff yesterday's payload against today's",
      "url": "https://fluentedi.com/v1/api/diff?baseline=%7B%22sku%22%3A%22X1%22%2C%22qty%22%3A4%7D&observed=%7B%22sku%22%3A%22X1%22%2C%22qty%22%3A%224%22%7D",
      "args": {
        "baseline": "{\"sku\":\"X1\",\"qty\":4}",
        "observed": "{\"sku\":\"X1\",\"qty\":\"4\"}"
      }
    }
  ],
  "suggestion": null
}