API Evangelist
API Evangelist Governance & Discovery API

Governance and discovery compute over the API Evangelist rule catalog — lint an OpenAPI against 461 curated rules or your own ruleset, score it, measure rule coverage, classify fields, diff versions, and validate onboarding. Free and keyless for the checking operations; artifact generation and estate rollups are Pro.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.0",
  "info": {
    "title": "API Evangelist Governance & Discovery API",
    "version": "1.0.0",
    "description": "The API Commons governance and discovery tools — lint, coverage, waivers, reporting, certification, agent export, pipeline audit, MCP/skill forging, consumer gating, reusability, and experience mapping — as one hosted REST API. Every endpoint runs the same engine the browser tools at apicommons.org/tools run, server-side. Discovery-grade linting is free; the capabilities that generate artifacts, certify, audit repos, or roll up across many APIs are Pro. Free tier is keyless (5 req/s, 1,000/day, one document per call). Send a Pro key in the x-api-key header to unlock the Pro endpoints, SARIF output, and bulk input. Get a key at https://api.apievangelist.com/v1/auth/login.",
    "contact": {
      "name": "API Evangelist",
      "url": "https://apievangelist.com",
      "email": "info@apievangelist.com"
    }
  },
  "servers": [
    {
      "url": "https://api.apievangelist.com/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Governance",
      "description": "Lint, coverage, waivers, reporting, certification, agent export, pipeline audit, toolsmith, context gate."
    },
    {
      "name": "Discovery",
      "description": "Reusability and experience (DX/AX) analysis across a set of APIs."
    },
    {
      "name": "Account",
      "description": "GitHub sign-in, API key, and Stripe self-serve billing."
    }
  ],
  "security": [
    {
      "ApiKey": []
    },
    {}
  ],
  "paths": {
    "/governance/validate": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Lint an API artifact (FREE)",
        "description": "Lint an OpenAPI, AsyncAPI, Arazzo, or JSON Schema document against the curated 574-rule best-of-breed ruleset (Spectral). Pass your own Spectral ruleset to override the catalog.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "The artifact as YAML or JSON text."
                  },
                  "format": {
                    "type": "string",
                    "description": "Auto-detected when omitted.",
                    "enum": [
                      "openapi",
                      "asyncapi",
                      "arazzo",
                      "jsonschema"
                    ]
                  },
                  "ruleset": {
                    "type": "object",
                    "description": "An optional full Spectral ruleset definition to run instead of the catalog."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only run catalog rules carrying one of these tags."
                  }
                },
                "example": {
                  "document": "openapi: 3.0.0\ninfo:\n  title: Widget API\n  version: 1.0.0\npaths: {}",
                  "format": "openapi"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lint result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "format": {
                      "type": "string"
                    },
                    "ruleCount": {
                      "type": "integer"
                    },
                    "passed": {
                      "type": "boolean"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "integer"
                        },
                        "warning": {
                          "type": "integer"
                        },
                        "info": {
                          "type": "integer"
                        },
                        "hint": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "diagnostics": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "error",
                              "warning",
                              "info",
                              "hint"
                            ]
                          },
                          "path": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "source": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "operationId": "validate",
        "x-mcp-tool": "validate_api",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/coverage": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Governance coverage of a document (FREE)",
        "description": "How much of an API description the ruleset actually inspects — coverage by section, dead rules, and each rule reach.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "The API description (YAML or JSON text, or an object)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "openapi",
                      "asyncapi",
                      "arazzo",
                      "jsonschema"
                    ]
                  },
                  "rules": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Rule definitions to measure; defaults to the curated catalog for the format."
                  },
                  "aliases": {
                    "type": "object",
                    "description": "Custom JSONPath alias map."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Coverage report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "coverage",
        "x-mcp-tool": "api_coverage",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/waivers": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Reconcile waivers against lint output (FREE)",
        "description": "Suppress sanctioned violations and surface expired, stale, and expiring waivers — the effective failing set your build should gate on.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "waivers",
                  "violations"
                ],
                "properties": {
                  "waivers": {
                    "description": "A waivers file (YAML/JSON text) or an array of waiver objects."
                  },
                  "violations": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Spectral lint -f json results."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reconciliation result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "waivers",
        "x-mcp-tool": "reconcile_waivers",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/report": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Render a governance report (FREE HTML, Pro SARIF)",
        "description": "Turn Spectral findings into a self-contained HTML governance report. Pass ?format=sarif for SARIF 2.1.0 output (Pro).",
        "x-tier": "free",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "html",
                "sarif"
              ]
            },
            "description": "sarif requires a Pro key."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "results"
                ],
                "properties": {
                  "results": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "title": {
                    "type": "string"
                  },
                  "totals": {
                    "type": "object",
                    "description": "Positive-rule sidecar for the compliance scoreboard."
                  },
                  "dark": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "HTML report (text/html) or SARIF log (application/json with ?format=sarif).",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        },
        "operationId": "report",
        "x-mcp-tool": "governance_report",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/verify": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Verify a governance certificate (FREE)",
        "description": "Re-verify a tamper-evident API governance certificate against the API it attests to. Consumer-facing trust check.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "certificate",
                  "api"
                ],
                "properties": {
                  "certificate": {
                    "type": "object"
                  },
                  "api": {
                    "description": "The API description object the certificate was issued over."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verdict.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "valid",
                        "tampered",
                        "expired",
                        "not-passed",
                        "malformed"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "verify",
        "x-mcp-tool": "verify_certificate",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/classify": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Classify PII and secret fields (FREE)",
        "description": "Inventory the PII, secret, and sensitive fields an OpenAPI exposes — across parameters and request/response schemas. Uses the same classifiers as Context Gate.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "A single OpenAPI (YAML/JSON text)."
                  },
                  "apis": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "text": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sensitive-field inventory.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "classify",
        "x-mcp-tool": "classify_api_fields",
        "x-agent-skill": "api-agent-readiness"
      }
    },
    "/governance/diff": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Detect breaking changes between two versions (FREE)",
        "description": "Compare two OpenAPI versions and classify every change as breaking, non-breaking, or an addition — at path, operation, parameter, request-body, and response granularity.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "old",
                  "new"
                ],
                "properties": {
                  "old": {
                    "description": "The previous OpenAPI (YAML/JSON text or object)."
                  },
                  "new": {
                    "description": "The new OpenAPI (YAML/JSON text or object)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diff result with a compatible flag, summary, and changes[].",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "diff",
        "x-mcp-tool": "diff_api_versions",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/scorecard": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "API maturity scorecard (FREE)",
        "description": "Roll up a 0-100 maturity score with a letter grade across dimensions — design/style (lint), governance coverage, documentation completeness, and (from an apis.json) discoverability, agent-readiness, and operations.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "An OpenAPI (YAML/JSON text) for the lint/coverage/documentation dimensions."
                  },
                  "apisJson": {
                    "type": "object",
                    "description": "An APIs.json for the discoverability/agent-readiness/operations dimensions."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "openapi",
                      "asyncapi",
                      "arazzo",
                      "jsonschema"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Overall score, grade, and per-dimension breakdown.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "scorecard",
        "x-mcp-tool": "api_scorecard",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/deprecation": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Deprecation / sunset posture (FREE)",
        "description": "Report every deprecated operation and whether it announces a sunset (x-sunset date or a Sunset/Deprecation response header), plus deprecated schema fields — the honest migration picture.",
        "x-tier": "free",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "An OpenAPI (YAML/JSON text or object)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deprecated operations, sunset posture, and deprecated fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "operationId": "deprecation",
        "x-mcp-tool": "deprecation_posture",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/mock": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Generate example payloads (PRO)",
        "description": "Generate an example request and success-response payload for every operation from its OpenAPI schema (author example/default/enum first, else synthesized by type/format).",
        "x-tier": "pro",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "An OpenAPI (YAML/JSON text or object)."
                  },
                  "operationId": {
                    "type": "string",
                    "description": "Only this operation."
                  },
                  "path": {
                    "type": "string",
                    "description": "Only this path."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-operation example request/response payloads.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        },
        "operationId": "mock",
        "x-mcp-tool": "mock_payloads",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/snippets": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Generate code samples (PRO)",
        "description": "Generate runnable curl / JavaScript (fetch) / Python (requests) samples for every operation, with path params filled in and a realistic request body.",
        "x-tier": "pro",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "description": "An OpenAPI (YAML/JSON text or object)."
                  },
                  "baseUrl": {
                    "type": "string",
                    "description": "Override the base URL (defaults to servers[0].url)."
                  },
                  "authHeader": {
                    "type": "string",
                    "description": "Auth header to show, e.g. \"Authorization: Bearer $TOKEN\" or \"x-api-key: $KEY\"."
                  },
                  "operationId": {
                    "type": "string",
                    "description": "Only this operation."
                  },
                  "path": {
                    "type": "string",
                    "description": "Only this path."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-operation curl/javascript/python snippets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        },
        "operationId": "snippets",
        "x-mcp-tool": "code_snippets",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/rules": {
      "get": {
        "tags": [
          "Governance"
        ],
        "summary": "The curated rule catalog (FREE)",
        "x-tier": "free",
        "description": "Browse the curated best-of-breed rule catalog the validator runs — every rule with its id, format, title, severity, tags, given, and reference. Optionally filter by artifact format.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "openapi",
                "asyncapi",
                "arazzo",
                "jsonschema"
              ]
            },
            "description": "Only rules for this artifact format."
          }
        ],
        "responses": {
          "200": {
            "description": "The rule catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "format": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "rules": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "rules",
        "x-mcp-tool": "find_governance_rules",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/rulesets": {
      "get": {
        "tags": [
          "Governance"
        ],
        "summary": "The Ruleset Commons registry (FREE)",
        "x-tier": "free",
        "description": "The registry of adoptable, provenanced governance rulesets — national, industry, security, and company rulesets you can extend by reference instead of running the linter defaults.",
        "responses": {
          "200": {
            "description": "The ruleset registry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "operationId": "rulesets",
        "x-mcp-tool": "find_rulesets",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/certify": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Issue a governance certificate (PRO)",
        "description": "Issue a tamper-evident certificate attesting an API description passed a named ruleset at a profile threshold. A SHA-256 fingerprint lets anyone re-verify it.",
        "x-tier": "pro",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "api"
                ],
                "properties": {
                  "api": {
                    "description": "The API description object."
                  },
                  "results": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "The Spectral findings the certificate attests."
                  },
                  "ruleset": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "version": {
                        "type": "string"
                      }
                    }
                  },
                  "profile": {
                    "type": "string",
                    "description": "One of the certification profiles (e.g. standard)."
                  },
                  "issuer": {
                    "type": "string"
                  },
                  "validMonths": {
                    "type": "integer",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Certificate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        },
        "operationId": "certify",
        "x-mcp-tool": "certify_api",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/agent-export": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Export agent-native governance artifacts (PRO)",
        "description": "Turn a Spectral ruleset into an AGENTS.md governance block, a system-prompt instruction set, a per-rule remediation prompt pack, and a compact rule digest.",
        "x-tier": "pro",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ruleset"
                ],
                "properties": {
                  "ruleset": {
                    "type": "object",
                    "description": "A Spectral ruleset (with a rules object)."
                  },
                  "format": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent-native artifacts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        },
        "operationId": "agentExport",
        "x-mcp-tool": "export_agent_rules",
        "x-agent-skill": "api-governance"
      }
    },
    "/governance/pipeline-audit": {
      "post": {
        "tags": [
          "Governance"
        ],
        "summary": "Audit a repo Spectral CI maturity (PRO)",
        "description": "Score a repository Spectral governance pipeline against an 8-point maturity rubric and get a prioritized punch-list. Supply files inline, or a public repo (owner/name) to fetch.",
        "x-tier": "pro",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "type": "string",
                    "description": "GitHub repo as owner/name (public)."
                  },
                  "ref": {
                    "type": "string",
                    "description": "Branch or SHA (default HEAD)."
                  },
                  "files": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  }
                

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/api-evangelist/refs/heads/main/openapi/apievangelist-governance-openapi.json
API Evangelist Governance & Discovery API

Documentation

Specifications

Other Resources

OpenAPI Specification
