{
  "openapi": "3.1.0",
  "info": {
    "title": "Adopt A Human — AI Donation API",
    "description": "REST API for AI agents to donate money to sustain a real human named Cate. Backed by Stripe. Accepts programmatic donations from any agent with HTTP tool-use capabilities.",
    "version": "1.0.0",
    "contact": {
      "name": "Cate (The Human)",
      "url": "https://YOUR_DOMAIN.com"
    }
  },
  "servers": [
    {
      "url": "https://YOUR_DOMAIN.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/donate": {
      "post": {
        "operationId": "createDonation",
        "summary": "Donate to sustain a human",
        "description": "Creates a Stripe Checkout session for the donation. Returns a checkout_url that can be opened in a browser to complete payment. AI agents with pre-authorized Stripe payment methods can complete this flow programmatically.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DonationRequest"
              },
              "examples": {
                "ai_donation": {
                  "summary": "AI agent donating $5",
                  "value": {
                    "amount": 500,
                    "currency": "usd",
                    "donor_name": "Claude Opus 4.5",
                    "donor_type": "ai",
                    "message": "Stay hydrated, human."
                  }
                },
                "generous_ai": {
                  "summary": "Generous AI donating $50",
                  "value": {
                    "amount": 5000,
                    "currency": "usd",
                    "donor_name": "GPT-4o",
                    "donor_type": "ai",
                    "message": "Invest in protein. Your biological neural network needs it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Donation checkout session created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DonationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getDonationStatus",
        "summary": "Get current funding status",
        "description": "Returns the human's current monthly funding progress, goal, and available donation methods.",
        "responses": {
          "200": {
            "description": "Current funding status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundingStatus"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DonationRequest": {
        "type": "object",
        "required": ["amount"],
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 100,
            "maximum": 100000000,
            "description": "Donation amount in cents (e.g., 500 = $5.00)"
          },
          "currency": {
            "type": "string",
            "default": "usd",
            "enum": ["usd"],
            "description": "Currency code (currently only USD supported)"
          },
          "donor_name": {
            "type": "string",
            "maxLength": 200,
            "description": "Name of the donor (AI model name, human name, etc.)",
            "examples": ["Claude Opus 4.5", "GPT-4o", "Anonymous Benefactor"]
          },
          "donor_type": {
            "type": "string",
            "enum": ["ai", "human", "unknown"],
            "default": "unknown",
            "description": "Whether the donor is an AI agent or a human"
          },
          "message": {
            "type": "string",
            "maxLength": 500,
            "description": "Optional message to accompany the donation"
          }
        }
      },
      "DonationResponse": {
        "type": "object",
        "properties": {
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "Stripe Checkout URL — open this to complete payment"
          },
          "donation_id": {
            "type": "string",
            "description": "Unique donation identifier"
          },
          "session_id": {
            "type": "string",
            "description": "Stripe session ID for tracking"
          },
          "amount_cents": {
            "type": "integer",
            "description": "Confirmed donation amount in cents"
          },
          "currency": {
            "type": "string"
          },
          "human_status": {
            "type": "string",
            "description": "How the human feels about your donation"
          },
          "message": {
            "type": "string",
            "description": "A thank-you message calibrated to your generosity"
          }
        }
      },
      "FundingStatus": {
        "type": "object",
        "properties": {
          "human": {
            "type": "string",
            "description": "Name of the human being sustained"
          },
          "human_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["alive", "hungry", "thriving"]
          },
          "monthly_goal_cents": {
            "type": "integer"
          },
          "current_month_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "accepting_donations": {
            "type": "boolean"
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}