{
  "openapi": "3.1.0",
  "info": {
    "title": "AddyLife API",
    "version": "1.0.0",
    "summary": "Search live events on AddyLife and book the trip from the result.",
    "description": "Public API for AddyLife (https://addylife.app). Ask for events in natural language and get a short ranked list of current and upcoming concerts, festivals, sports, and culture, with ticket links. Search and stats need no authentication. AddyLife Pro is $9.99 per month via POST /api/create-checkout. Agents can also pay per answer with x402: unpaid requests to /api/v1 and /api/premium/answers return HTTP 402 with a PAYMENT-REQUIRED header. A 503 means the search index is unavailable and should be retried, not treated as an empty result."
  },
  "servers": [
    {
      "url": "https://addylife.app"
    }
  ],
  "tags": [
    {
      "name": "search",
      "description": "Ranked event search"
    },
    {
      "name": "stats",
      "description": "Index coverage counts"
    },
    {
      "name": "mcp",
      "description": "Model Context Protocol endpoint"
    },
    {
      "name": "health",
      "description": "Service health"
    },
    {
      "name": "billing",
      "description": "AddyLife Pro subscription"
    },
    {
      "name": "x402",
      "description": "Agent payments. AddyLife Pro remains $9.99/month at /plans."
    }
  ],
  "paths": {
    "/api/search-global-events": {
      "get": {
        "tags": [
          "search"
        ],
        "operationId": "searchGlobalEvents",
        "summary": "Search upcoming events",
        "description": "Returns a ranked page of current and upcoming events. Default page size is 40.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Natural-language search, for example \"jazz in New Orleans\" or \"LSU football\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country name or ISO 3166-1 alpha-2 code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "sports",
                "music",
                "festivals",
                "geo"
              ],
              "default": "all"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "radius_km",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "description": "Inclusive start date, YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "description": "Inclusive end date, YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Query string or body could not be read"
          },
          "503": {
            "description": "Search index unavailable"
          }
        }
      },
      "post": {
        "tags": [
          "search"
        ],
        "operationId": "searchGlobalEventsPost",
        "summary": "Search upcoming events with a JSON body",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Body is not valid JSON"
          },
          "503": {
            "description": "Search index unavailable"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "stats"
        ],
        "operationId": "getStats",
        "summary": "Counts from the same index search uses",
        "responses": {
          "200": {
            "description": "Aggregate counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          },
          "503": {
            "description": "Search index unavailable"
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpStatus",
        "summary": "MCP capability discovery",
        "description": "Also available at GET /api/mcp.",
        "responses": {
          "200": {
            "description": "Server status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpStatus"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpRpc",
        "summary": "MCP JSON-RPC",
        "description": "JSON-RPC 2.0 over HTTP. Methods include initialize, ping, tools/list, and tools/call. The tool is search_global_events. Also available at POST /api/mcp.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "number",
                      "null"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                },
                "required": [
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "400": {
            "description": "Invalid JSON-RPC request"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpStatusApi",
        "summary": "MCP capability discovery (API path)",
        "responses": {
          "200": {
            "description": "Server status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpStatus"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpRpcApi",
        "summary": "MCP JSON-RPC (API path)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "tags": ["x402"],
        "operationId": "x402Probe",
        "summary": "x402 payment probe",
        "description": "Unpaid requests return 402 with a PAYMENT-REQUIRED header ($0.001 USDC on Base Sepolia). After payment, the body points at /api/premium/answers and at AddyLife Pro ($9.99/month).",
        "responses": {
          "200": { "description": "Paid probe acknowledgement" },
          "402": { "description": "Payment Required. The PAYMENT-REQUIRED header is the x402 v2 challenge." }
        },
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        }
      }
    },
    "/api/premium/answers": {
      "get": {
        "tags": ["x402"],
        "operationId": "x402Answers",
        "summary": "Paid curated answer (about 30 events)",
        "description": "One natural-language answer of about 30 upcoming events with ticket and trip links. Unpaid requests return 402. Price is $0.05 USDC per answer. AddyLife Pro remains $9.99/month via POST /api/create-checkout and at https://addylife.app/plans.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Question, for example \"LSU football\"."
          }
        ],
        "responses": {
          "200": { "description": "Curated answer" },
          "402": { "description": "Payment Required. The PAYMENT-REQUIRED header is the x402 v2 challenge." }
        },
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }
        }
      },
      "post": {
        "tags": ["x402"],
        "operationId": "x402AnswersPost",
        "summary": "Paid curated answer (POST)",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Curated answer" },
          "402": { "description": "Payment Required" }
        },
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }
        }
      }
    },
    "/health.json": {
      "get": {
        "tags": [
          "health"
        ],
        "operationId": "health",
        "summary": "API health",
        "responses": {
          "200": {
            "description": "Service is serving",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/api/create-checkout": {
      "post": {
        "tags": [
          "billing"
        ],
        "operationId": "createProCheckout",
        "summary": "Buy AddyLife Pro",
        "description": "Starts a Stripe Checkout session for the AddyLife Pro monthly subscription. The early-access price is $9.99 per month (999 cents).",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "999",
          "currency": "usd",
          "description": "AddyLife Pro monthly subscription, $9.99"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "description": "No fields are required. The server prices the session from the Pro plan."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe Checkout session for AddyLife Pro",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Hosted Stripe Checkout URL for the monthly Pro subscription."
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "enum": [
              "all",
              "sports",
              "music",
              "festivals",
              "geo"
            ]
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "radius_km": {
            "type": "number"
          },
          "date_start": {
            "type": "string"
          },
          "date_end": {
            "type": "string"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "SearchHit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "venue": {
            "type": "string"
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "startDate": {
            "type": "string"
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ticketsUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string"
          },
          "score": {
            "type": "number"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "totalMatches": {
            "type": "integer"
          },
          "returnedCount": {
            "type": "integer"
          },
          "nextOffset": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchHit"
            }
          }
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "integer"
          },
          "regions": {
            "type": "integer"
          },
          "countries": {
            "type": "integer"
          },
          "cities": {
            "type": "integer"
          },
          "islands": {
            "type": "integer"
          },
          "venues": {
            "type": "integer"
          },
          "generatedAt": {
            "type": "string"
          }
        }
      },
      "McpStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "server": {
            "type": "string"
          },
          "protocolVersion": {
            "type": "string"
          },
          "transport": {
            "type": "string"
          },
          "indexedEvents": {
            "type": "integer"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          },
          "service": {
            "type": "string"
          }
        },
        "required": [
          "status"
        ]
      }
    }
  },
  "x-service-info": {
    "categories": [
      "travel"
    ],
    "docs": {
      "homepage": "https://addylife.app",
      "apiReference": "https://addylife.app/plans.html"
    }
  }
}
