API Evangelist Discovery API

openapi: 3.2.0
info:
  title: 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
security:
- ApiKey: []
- {}
tags:
- name: Discovery
  description: Reusability and experience (DX/AX) analysis across a set of APIs.
paths:
  /discovery/reusability:
    post:
      tags:
      - Discovery
      summary: Reusability and duplication across APIs (PRO)
      description: Score how reusable a set of APIs is and detect duplication/overlap across them; optionally score apis.json composability and metadata completeness.
      x-tier: pro
      security:
      - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                apis:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      openapi:
                        type: string
                properties:
                  type: array
                  items:
                    type: object
                  description: apis.json properties for composability/metadata scoring.
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Reuse and duplication scores.
          content:
            application/json:
              schema:
                type: object
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      operationId: reusability
      x-mcp-tool: score_reusability
      x-agent-skill: api-governance
  /discovery/onboarding:
    post:
      tags:
      - Discovery
      summary: Validate an API Onboarding Descriptor (FREE)
      description: Validate an API Onboarding Descriptor (AID) against the api-commons AID JSON Schema, and report which optional sections it fills in (a completeness score).
      x-tier: free
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - descriptor
              properties:
                descriptor:
                  description: An API Onboarding Descriptor (object or JSON text).
      responses:
        '200':
          description: Validity, errors[], maturity, and completeness.
          content:
            application/json:
              schema:
                type: object
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: onboarding
      x-mcp-tool: validate_onboarding
      x-agent-skill: api-agent-readiness
  /discovery/agent-descriptor:
    post:
      tags:
      - Discovery
      summary: Generate llms.txt + AGENTS.md (PRO)
      description: 'Generate the agent-facing descriptors for an API: an llms.txt (well-known link summary) and an AGENTS.md consumption contract — base URL, auth, the operation table, deprecated operations to avoid, and usage rules. Reads links from an apis.json when supplied.'
      x-tier: pro
      security:
      - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document:
                  type: string
                  description: An OpenAPI (YAML/JSON text or object).
                apisJson:
                  type: object
                  description: An APIs.json whose properties supply the docs/OpenAPI/MCP/pricing links.
      responses:
        '200':
          description: llmsTxt + agentsMd, with operation/deprecation counts.
          content:
            application/json:
              schema:
                type: object
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      operationId: agentDescriptor
      x-mcp-tool: generate_agent_descriptor
      x-agent-skill: api-agent-readiness
  /discovery/experience:
    post:
      tags:
      - Discovery
      summary: DX/AX experience coverage (PRO)
      description: Map each REST operation to its MCP tool and Agent Skill (the API to MCP to Agent-Skill chain) from an APIs.json, with a free/paid coverage scorecard and an SVG flow map.
      x-tier: pro
      security:
      - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                apisJson:
                  type: object
                  description: An APIs.json document (with an apis array).
      responses:
        '200':
          description: Experience model, coverage, and SVG.
          content:
            application/json:
              schema:
                type: object
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      operationId: experience
      x-mcp-tool: map_api_experience
      x-agent-skill: api-agent-readiness
components:
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
    PaymentRequired:
      description: This capability requires a Pro plan.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: payment_required
              message:
                type: string
              upgrade:
                type: string
                example: https://developer.apievangelist.com/plans
  headers:
    XRateLimitTier:
      description: The tier this request was served on — `free`, `pro`, `business`, `internal` or `owner`. Keyless requests are `free`; requests from an apievangelist.com origin are `internal`.
      schema:
        type: string
        examples:
        - free
    XRateLimitLimit:
      description: The daily request quota for the tier that served this response.
      schema:
        type: integer
        examples:
        - 1000
    XRateLimitWindow:
      description: The quota window in seconds. Always 86400 (one day).
      schema:
        type: integer
        examples:
        - 86400
    RateLimitPolicy:
      description: 'The rate-limit policy in force for the tier that served this response, in RFC 9331 quota-policy syntax: `"quota";q=1000;w=86400, "burst";q=5;w=1` — a daily quota and a per-second burst. This is the POLICY, not a live counter: `RateLimit-Remaining` and `RateLimit-Reset` are deliberately not sent, because the quota is enforced by the gateway and there is no per-key usage accounting to read. Pace against the policy, and treat a 429 as authoritative.'
      schema:
        type: string
        examples:
        - '"quota";q=1000;w=86400, "burst";q=5;w=1'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: A Pro or Team key from sign-in. Omit for keyless free-tier access.
x-apis-io:
  mcpServer: https://mcp.apievangelist.com
  agentSkills: https://raw.githubusercontent.com/api-commons/agent-skills/main/
  operations:
    validate:
      tier: free
      mcpTool: validate_api
      agentSkill: api-governance
    coverage:
      tier: free
      mcpTool: api_coverage
      agentSkill: api-governance
    waivers:
      tier: free
      mcpTool: reconcile_waivers
      agentSkill: api-governance
    report:
      tier: free
      mcpTool: governance_report
      agentSkill: api-governance
    verify:
      tier: free
      mcpTool: verify_certificate
      agentSkill: api-governance
    classify:
      tier: free
      mcpTool: classify_api_fields
      agentSkill: api-agent-readiness
    diff:
      tier: free
      mcpTool: diff_api_versions
      agentSkill: api-governance
    scorecard:
      tier: free
      mcpTool: api_scorecard
      agentSkill: api-governance
    deprecation:
      tier: free
      mcpTool: deprecation_posture
      agentSkill: api-governance
    mock:
      tier: pro
      mcpTool: mock_payloads
      agentSkill: api-governance
    snippets:
      tier: pro
      mcpTool: code_snippets
      agentSkill: api-governance
    rules:
      tier: free
      mcpTool: find_governance_rules
      agentSkill: api-governance
    rulesets:
      tier: free
      mcpTool: find_rulesets
      agentSkill: api-governance
    certify:
      tier: pro
      mcpTool: certify_api
      agentSkill: api-governance
    agentExport:
      tier: pro
      mcpTool: export_agent_rules
      agentSkill: api-governance
    pipelineAudit:
      tier: pro
      mcpTool: audit_pipeline
      agentSkill: api-governance
    toolsmith:
      tier: pro
      mcpTool: forge_mcp_tools
      agentSkill: api-agent-readiness
    contextGate:
      tier: pro
      mcpTool: gate_agent_context
      agentSkill: api-agent-readiness
    overlay:
      tier: pro
      mcpTool: apply_overlay
      agentSkill: api-governance
    reusability:
      tier: pro
      mcpTool: score_reusability
      agentSkill: api-governance
    onboarding:
      tier: free
      mcpTool: validate_onboarding
      agentSkill: api-agent-readiness
    agentDescriptor:
      tier: pro
      mcpTool: generate_agent_descriptor
      agentSkill: api-agent-readiness
    experience:
      tier: pro
      mcpTool: map_api_experience
      agentSkill: api-agent-readiness