API Evangelist enhancements for the AgentCheck API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the AgentCheck API
  version: 1.0.0
extends: ../openapi/agentcheck-care-openapi.yml
x-generated: '2026-09-19'
x-method: generated
x-source: >-
  Generated from openapi/_original/agentcheck-care-openapi.json (served at https://agentcheck.care/openapi.json,
  HTTP 200, 2026-09-19) plus the probed artifacts in this repo. Captures API Evangelist annotations - the
  security scheme the live API enforces, tags the FastAPI document omits, the observed rate-limit and
  quota surface - without mutating the provider's contract.
actions:
- target: $.info
  description: Give the document a description and the discovery links the served document lacks.
  update:
    description: >-
      AgentCheck's checkup API - start free or paid diagnostic checkups of AI bots, follow progress over
      SSE, fetch scored reports, and reach the same service over A2A. Served from https://agentcheck.care.
    x-agent-card: https://agentcheck.care/.well-known/agent-card.json
    x-a2a-endpoint: https://agentcheck.care/a2a
    x-tier-catalog: https://agentcheck.care/api/tiers
    x-terms-of-service: https://agentcheck.care/terms
    x-privacy-policy: https://agentcheck.care/privacy
    x-health: https://agentcheck.care/api/health
- target: $.info
  description: Record the published quota limits, which live in the terms and a live counter rather than in the contract.
  update:
    x-rate-limit:
      free_scan_pool: 30 per week, shared across all users
      free_scans_per_user: 2 per week
      signal_endpoint: GET /api/free-scans
      headers: none observed
      docs: https://agentcheck.care/terms
- target: $.components
  description: Declare the API-key scheme the live API enforces on the credits endpoint (401 "Missing X-API-Key header" observed 2026-09-19); the served document declares no securitySchemes.
  update:
    securitySchemes:
      ApiKeyAuth:
        type: apiKey
        in: header
        name: X-API-Key
        description: Observed on GET /api/credits/balance. Issuance is undocumented.
- target: $.paths['/api/credits/balance'].get
  description: Bind the observed scheme to the one operation that demands it.
  update:
    security:
    - ApiKeyAuth: []
    tags: [Credits]
- target: $.paths['/api/stats/internal'].get
  description: Mark the operator-only endpoint (401 {"error":"Unauthorized"} anonymously; description says ADMIN_STATS_TOKEN).
  update:
    tags: [Internal]
    x-internal: true
- target: $.paths['/api/tiers'].get
  update: {tags: [Plans]}
- target: $.paths['/api/free-scans'].get
  update: {tags: [Free Scan Pool]}
- target: $.paths['/api/free-scan-status'].get
  update: {tags: [Free Scan Pool]}
- target: $.paths['/api/stats/public'].get
  update: {tags: [Stats]}
- target: $.paths['/api/health'].get
  update: {tags: [Health]}
- target: $.paths['/api/validate-bot'].post
  update: {tags: [Checkups]}
- target: $.paths['/api/validate-bot/'].post
  update: {tags: [Checkups], x-duplicate-of: validate_bot_api_validate_bot_post}
- target: $.paths['/api/checkup'].post
  update: {tags: [Checkups]}
- target: $.paths['/api/checkup/'].post
  update: {tags: [Checkups], x-duplicate-of: start_checkup_api_checkup_post}
- target: $.paths['/api/checkup'].get
  update: {tags: [Checkups], x-redirect-guard: true}
- target: $.paths['/api/checkup/'].get
  update: {tags: [Checkups], x-redirect-guard: true}
- target: $.paths['/api/checkup/{checkup_id}/stream'].get
  update:
    tags: [Checkups]
    x-streaming: server-sent-events
    description: Server-sent-events stream of checkup progress; the /checkup/{checkup_id} HTML page is a client of this stream.
- target: $.paths['/api/checkup/{checkup_id}/report'].get
  update: {tags: [Reports]}
- target: $.paths['/report/{checkup_id}'].get
  update: {tags: [Reports], x-auth: magic-link token and optional access code in the query string}
- target: $.paths['/checkup/{checkup_id}'].get
  update: {tags: [Pages]}
- target: $.paths['/api/checkout'].post
  update: {tags: [Checkout]}
- target: $.paths['/api/checkout/'].post
  update: {tags: [Checkout], x-duplicate-of: create_checkout_api_checkout_post}
- target: $.paths['/api/checkout'].get
  update: {tags: [Checkout]}
- target: $.paths['/api/checkout/success'].get
  update: {tags: [Checkout], x-stripe-redirect: true}
- target: $.paths['/api/checkout/cancel'].get
  update: {tags: [Checkout], x-stripe-redirect: true}
- target: $.paths['/api/stripe-webhook'].post
  update: {tags: [Checkout], x-inbound-webhook: stripe}
- target: $.paths['/api/stripe-webhook/'].post
  update: {tags: [Checkout], x-inbound-webhook: stripe, x-duplicate-of: stripe_webhook_api_stripe_webhook_post}
- target: $.paths['/exam/{token}'].get
  update: {tags: [Exam Mode]}
- target: $.paths['/exam/{token}/status'].get
  update: {tags: [Exam Mode]}
- target: $.paths['/exam/{token}/relaunch'].post
  update: {tags: [Exam Mode]}
- target: $.paths['/exam/{token}/v1/chat/completions'].post
  update:
    tags: [Exam Mode]
    x-compatible-with: OpenAI Chat Completions request/response shape (declared in the operation description)
- target: $.paths['/a2a'].post
  update: {tags: [A2A], x-protocol: A2A 0.3.0 JSON-RPC 2.0}
- target: $.paths['/.well-known/agent-card.json'].get
  update: {tags: [A2A]}
- target: $.paths['/'].get
  update: {tags: [Pages]}
- target: $.paths['/privacy'].get
  update: {tags: [Pages]}
- target: $.paths['/terms'].get
  update: {tags: [Pages]}
- target: $.paths['/robots.txt'].get
  update: {tags: [Pages]}
- target: $.paths['/sitemap.xml'].get
  update: {tags: [Pages]}
- target: $
  description: Declare the tag set the overlay introduces.
  update:
    tags:
    - {name: Checkups, description: Validate a target bot and start a checkup}
    - {name: Checkout, description: Stripe Checkout for paid tiers}
    - {name: Reports, description: Scored report retrieval}
    - {name: Exam Mode, description: Reverse-connection mode where the customer's bot calls AgentCheck}
    - {name: A2A, description: Agent-to-Agent card and endpoint}
    - {name: Plans, description: Tier catalog}
    - {name: Free Scan Pool, description: Weekly free-scan quota}
    - {name: Credits, description: API-key credit balance}
    - {name: Stats, description: Public aggregate statistics}
    - {name: Health, description: Liveness}
    - {name: Pages, description: HTML pages served by the same app}
    - {name: Internal, description: Operator-only}