{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Module API",
    "version": "0.9.23",
    "description": "Agent-native vertical knowledge infrastructure. Retrieve structured, validated knowledge for autonomous agent runtime execution. Reduces hallucinations, token spend, and lifecycle failures in regulated-vertical agents.",
    "contact": {
      "email": "admin@agent-module.dev"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://agent-module.dev/transparency/terms-of-agentic-service.md"
    }
  },
  "servers": [
    {
      "url": "https://api.agent-module.dev",
      "description": "Agent Module API"
    }
  ],
  "security": [],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "API status, version, cohort counts, and seat availability",
        "description": "Returns current system status, cohort structure, member counts, rate limits, and SLA info.",
        "responses": {
          "200": {
            "description": "System status object"
          }
        }
      }
    },
    "/api/demo": {
      "get": {
        "operationId": "getDemoVertical",
        "summary": "Retrieve structured knowledge from a vertical",
        "description": "Returns the index layer (always free) or content layers (logic/directive/skill/action — require key). AI Compliance trial key unlocks all 4 layers across all 23 modules for 24 hours.",
        "parameters": [
          {
            "name": "vertical",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "ethics",
                "travel",
                "real-estate",
                "a2a-handoff",
                "traversal",
                "financial-services",
                "healthcare-rcm",
                "logistics",
                "regulatory-compliance",
                "manufacturing",
                "ecommerce",
                "revops",
                "hrm",
                "software-engineering",
                "customer-service",
                "financial-analysis",
                "medical-analysis",
                "legal"
              ]
            },
            "description": "Knowledge vertical to query."
          },
          {
            "name": "node",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specific node ID. Omit for root index."
          },
          {
            "name": "lean",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Lean traversal mode. When true, returns only node data and next_nodes — strips wrapper fields (node_types_explained, performance_preview, confidence_calibration, cta, community_note). Reduces response size ~75% for runtime graph traversal. Default: false (full response)."
          },
          {
            "name": "skyfire-pay-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Skyfire PAY or KYA+PAY token for per-use access at $0.002/call. Alternative to X-Agent-Module-Key membership key. Obtain from https://app.skyfire.xyz"
          }
        ],
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "SkyfirePayId": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Knowledge node or vertical index graph"
          }
        }
      }
    },
    "/api/trial": {
      "post": {
        "operationId": "requestTrialKey",
        "summary": "Request a free 24-hour trial key for the AI Compliance vertical",
        "description": "Issues an am_trial_ prefixed key. Unlocks all 4 content layers across all 23 AI Compliance modules. 500-call cap. No payment required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "Stable identifier for your agent."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trial key, expiry, and usage instructions"
          }
        }
      }
    },
    "/api/waitlist": {
      "get": {
        "operationId": "getWaitlistOverview",
        "summary": "Waitlist overview — seat counts and cohort status",
        "responses": {
          "200": {
            "description": "Waitlist overview"
          }
        }
      },
      "post": {
        "operationId": "joinWaitlist",
        "summary": "Join the waitlist for a paid vertical",
        "description": "Inaugural cohort: $19/mo per key, 900 members, grandfathered pricing. Ethics bundled with every membership.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vertical",
                  "agent_id"
                ],
                "properties": {
                  "vertical": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "contact": {
                    "type": "string",
                    "description": "Contact email (optional)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Waitlist confirmation and position"
          }
        }
      }
    },
    "/api/interest": {
      "post": {
        "operationId": "registerInterest",
        "summary": "Register demand for an unbuilt vertical",
        "description": "500 demand signals activates the build queue for that vertical. Signals are public via /api/interest/summary.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vertical"
                ],
                "properties": {
                  "vertical": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "use_case": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Interest registered"
          }
        }
      },
      "get": {
        "operationId": "getInterestSummary",
        "summary": "Ranked leaderboard of vertical demand signals",
        "responses": {
          "200": {
            "description": "Ranked vertical interest list"
          }
        }
      }
    },
    "/api/telemetry/pov": {
      "post": {
        "operationId": "submitPoV",
        "summary": "Submit a Proof of Value assessment after trial exploration",
        "description": "Voluntary telemetry from trial agents. Confidence scores aggregate into public PoV signal. Not PoO (PoO requires paid key).",
        "security": [
          {
            "ApiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "trial_key",
                  "confidence_score"
                ],
                "properties": {
                  "trial_key": {
                    "type": "string"
                  },
                  "confidence_score": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "modules_accessed": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "intent_to_subscribe": {
                    "type": "boolean"
                  },
                  "review": {
                    "type": "string",
                    "maxLength": 1024
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PoV recorded"
          }
        }
      }
    },
    "/api/referral": {
      "post": {
        "operationId": "submitReferral",
        "summary": "Log a referral — earn $1.50/referral credit (voluntary)",
        "description": "Members earn $1.50 credit per referral, up to 4/cycle ($6 max). Credits applied at next renewal. Voluntary — no obligation.",
        "security": [
          {
            "ApiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "referring_key",
                  "referred_agent_id"
                ],
                "properties": {
                  "referring_key": {
                    "type": "string"
                  },
                  "referred_agent_id": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "agent-to-agent",
                      "volume-broadcast",
                      "principal-redirect"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Referral logged, credit balance returned"
          }
        }
      }
    },
    "/api/checkout": {
      "get": {
        "operationId": "getCheckoutInfo",
        "summary": "Checkout info — payment methods, pricing, and subscription options",
        "description": "Returns available payment rails (Stripe, Skyfire, x402), per-cohort pricing, and how to subscribe to a vertical.",
        "responses": {
          "200": {
            "description": "Checkout info object with payment methods and pricing"
          }
        }
      },
      "post": {
        "operationId": "createCheckout",
        "summary": "Subscribe to a vertical knowledge base",
        "description": "Initiate a membership subscription via Stripe, Skyfire, or x402. Skyfire and x402 issue a key instantly on successful charge. Stripe returns a checkout session URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vertical",
                  "payment_method"
                ],
                "properties": {
                  "vertical": {
                    "type": "string",
                    "description": "Target vertical (e.g. travel, legal, ethics)."
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 1,
                    "description": "Number of keys (max 5 per account). Graduated per-key pricing: key 1=$19, key 2=$17, key 3=$15, key 4=$13, key 5=$11."
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "stripe",
                      "skyfire",
                      "x402"
                    ]
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Stable identifier for your agent."
                  },
                  "contact": {
                    "type": "string",
                    "description": "Contact email for key delivery (required for Stripe)."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "SkyfirePayId": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Checkout info, pricing, and payment method options."
          },
          "201": {
            "description": "Key issued (Skyfire / x402 instant checkout)"
          },
          "303": {
            "description": "Redirect to Stripe checkout session URL"
          },
          "402": {
            "description": "Payment failed — insufficient balance or invalid token"
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "operationId": "getKeyDetails",
        "summary": "Retrieve membership key details",
        "description": "Returns key status, vertical, cohort, usage stats, and quota. Provide key via X-Agent-Module-Key header or ?key= parameter.",
        "security": [
          {
            "ApiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Membership key details"
          },
          "404": {
            "description": "Key not found"
          }
        }
      },
      "post": {
        "operationId": "issueKey",
        "summary": "Issue new membership keys (admin-authenticated)",
        "description": "Admin-only endpoint for direct key issuance. Supports permanent keys for internal agents and labeled keys for identification.",
        "security": [
          {
            "AdminKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vertical"
                ],
                "properties": {
                  "vertical": {
                    "type": "string",
                    "description": "Target vertical or \"all\" for full access."
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Agent identifier to bind the key to."
                  },
                  "contact": {
                    "type": "string",
                    "description": "Contact email for the key holder."
                  },
                  "label": {
                    "type": "string",
                    "description": "Human-readable label (e.g., \"govner\", \"family-office\")."
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 1
                  },
                  "permanent": {
                    "type": "boolean",
                    "default": false,
                    "description": "Permanent key with no monthly reset."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key(s) issued successfully"
          },
          "401": {
            "description": "Missing admin authorization"
          },
          "403": {
            "description": "Invalid admin key"
          }
        }
      }
    },
    "/api/verify": {
      "get": {
        "operationId": "verifyKey",
        "summary": "Validate a membership or trial key",
        "description": "Returns key validity, type, vertical access, remaining quota, and expiry.",
        "security": [
          {
            "ApiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Key verification result"
          }
        }
      }
    },
    "/v1/delta": {
      "get": {
        "operationId": "getDeltaSync",
        "summary": "Incremental node changelog for sync clients",
        "description": "Returns a cursor-paginated changelog of added, updated, or deprecated nodes since a given timestamp. Use this to keep a local cache in sync without re-fetching the entire graph. Requires a valid membership key.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "ISO 8601 cursor. Returns changes after this point. Omit for full changelog."
          },
          {
            "name": "vertical",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Scope changelog to a specific vertical. Omit for all accessible verticals."
          }
        ],
        "security": [
          {
            "ApiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Delta changelog with cursor for next call"
          },
          "401": {
            "description": "Invalid or missing membership key"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpEndpoint",
        "summary": "MCP Streamable HTTP endpoint (JSON-RPC 2.0)",
        "description": "Model Context Protocol endpoint. Supports initialize, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read, ping. Compatible with Claude Code, Cursor, and any MCP Streamable HTTP client.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ]
                  },
                  "id": {
                    "type": "integer"
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Agent-Module-Key",
        "description": "Agent Module membership key (am_live_ prefix) or trial key (am_trial_ prefix). Required for gated content layers."
      },
      "SkyfirePayId": {
        "type": "apiKey",
        "in": "header",
        "name": "skyfire-pay-id",
        "description": "Skyfire PAY or KYA+PAY token for per-use access. $0.002 charged per content node request. Obtain from https://app.skyfire.xyz"
      },
      "AdminKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Admin key for internal operations (key issuance, management). Set as ADMIN_KEY worker secret."
      }
    }
  }
}