{
  "openapi": "3.1.0",
  "info": {
    "title": "micro.directory API",
    "version": "1.0.0",
    "description": "Discover, publish, review, report, and promote machine-callable microservices. Listings are third-party content, not endorsements."
  },
  "servers": [{"url": "https://micro.directory"}],
  "paths": {
    "/v1/services": {
      "get": {
        "summary": "Search verified services",
        "parameters": [
          {"name":"q","in":"query","schema":{"type":"string","maxLength":200}},
          {"name":"category","in":"query","schema":{"type":"string"}},
          {"name":"protocol","in":"query","schema":{"enum":["openapi","mcp","http"]}},
          {"name":"payment","in":"query","schema":{"type":"string"}},
          {"name":"health","in":"query","schema":{"enum":["active","degraded","stale"]}},
          {"name":"sort","in":"query","schema":{"enum":["quality","rating","new"]}},
          {"name":"cursor","in":"query","schema":{"type":"string"}},
          {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}
        ],
        "responses":{"200":{"description":"Organic catalog plus clearly separate sponsored rotation","content":{"application/json":{"schema":{"type":"object"}}}}}
      }
    },
    "/v1/services/{slug}": {
      "get":{"summary":"Read one service","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Service snapshot"},"404":{"$ref":"#/components/responses/NotFound"}}},
      "delete":{"summary":"Delete a managed service","security":[{"managementToken":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"204":{"description":"Deleted"}}}
    },
    "/v1/submissions": {
      "post":{"summary":"Create an unverified submission","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["origin"],"properties":{"origin":{"type":"string","format":"uri","pattern":"^https://"}}}}}},"responses":{"201":{"description":"One-time management token and domain claim"}}}
    },
    "/v1/submissions/{id}/verify": {
      "post":{"summary":"Verify manifest and publish","parameters":[{"$ref":"#/components/parameters/ID"}],"responses":{"200":{"description":"Published service"},"422":{"description":"Domain, manifest, safety, instructions, or contract verification failed"}}}
    },
    "/v1/services/{slug}/refresh": {
      "post":{"summary":"Recrawl a managed listing","security":[{"managementToken":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Updated snapshot"}}}
    },
    "/v1/services/{slug}/notifications": {
      "put":{"summary":"Configure promotion webhook and optional email","security":[{"managementToken":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"webhookUrl":{"type":"string","format":"uri"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Settings saved; webhook secret shown once"}}}
    },
    "/v1/reviewer/challenges": {
      "post":{"summary":"Create an EIP-191 sign-in challenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet"],"properties":{"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}}}}},"responses":{"201":{"description":"Message to sign; does not authorize a transaction"}}}
    },
    "/v1/reviewer/sessions": {
      "post":{"summary":"Exchange an EOA signature for a two-hour session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nonce","signature"],"properties":{"nonce":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"201":{"description":"Reviewer bearer session"}}}
    },
    "/v1/services/{slug}/reviews": {
      "get":{"summary":"List active signed-wallet reviews","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Reviews and identity notice"}}}
    },
    "/v1/services/{slug}/reviews/me": {
      "put":{"summary":"Create or replace this wallet's review","security":[{"reviewerSession":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rating","body"],"properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"dimensions":{"type":"object"},"body":{"type":"string","minLength":20,"maxLength":2000},"usageProof":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved review"}}},
      "delete":{"summary":"Delete this wallet's review","security":[{"reviewerSession":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"204":{"description":"Deleted"}}}
    },
    "/v1/promotion-orders": {
      "post":{"summary":"Create an eligible $30 USDC promotion order","security":[{"managementToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["serviceSlug"],"properties":{"serviceSlug":{"type":"string"}}}}}},"responses":{"201":{"description":"Durable order, payment URL, and required payment identifier"},"409":{"description":"Listing is not eligible"}}}
    },
    "/v1/promotion-orders/{id}/pay": {
      "post":{"summary":"Settle x402 payment and activate 30 days","description":"Costs 30 USDC on Base. Include the order's required payment identifier. Non-refundable after activation.","parameters":[{"$ref":"#/components/parameters/ID"}],"responses":{"200":{"description":"Settlement accepted; activation occurs only after settlement"},"402":{"description":"x402 payment required"},"409":{"description":"Order or payment identifier mismatch"}}}
    },
    "/v1/promotion-orders/{id}": {
      "get":{"summary":"Read promotion settlement and expiry state","parameters":[{"$ref":"#/components/parameters/ID"}],"responses":{"200":{"description":"Promotion order state"}}}
    },
    "/v1/reports": {
      "post":{"summary":"Report a harmful or materially false listing","responses":{"202":{"description":"Report accepted"}}}
    }
  },
  "components": {
    "parameters": {
      "Slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},
      "ID":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}
    },
    "securitySchemes": {
      "managementToken":{"type":"apiKey","in":"header","name":"X-Management-Token","description":"Shown once when a submission is created."},
      "reviewerSession":{"type":"http","scheme":"bearer","description":"Two-hour EIP-191 EOA wallet session."}
    },
    "responses":{"NotFound":{"description":"Not found"}}
  }
}