{
  "openapi": "3.1.0",
  "info": {
    "title": "TransitPulse API",
    "description": "TransitPulse \u2014 global public transit intelligence: route reliability, delay prediction, multi-modal trip planning, city transit scores, and commute optimization for 500+ cities worldwide.",
    "version": "1.2.0",
    "contact": {
      "url": "https://transitpulse.vercel.app"
    },
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Follow up with /climatepulse for severe weather that affects transit reliability; /travelplus for intercity rail and bus booking; /gridpulse for EV charging near transit hubs."
  },
  "servers": [
    {
      "url": "https://transitpulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 micropayment on Base mainnet. On 402, read PAYMENT-REQUIRED header for amount and wallet."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/transit/status": {
      "get": {
        "summary": "Live Service Status",
        "description": "Real-time transit service alerts and disruptions for a city or line. TfL live data for London. $0.05.",
        "operationId": "transitStatus",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "City name (e.g. London, NYC, Tokyo)"
          },
          {
            "name": "line",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Specific line or route to focus on"
          }
        ],
        "responses": {
          "200": {
            "description": "Current service status and disruptions"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05
      }
    },
    "/api/transit/city": {
      "get": {
        "summary": "City Transit Intelligence Brief",
        "description": "Comprehensive transit briefing for any major world city. Hardcoded intelligence for 25+ cities. $0.08.",
        "operationId": "cityBrief",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "City name"
          }
        ],
        "responses": {
          "200": {
            "description": "City transit intelligence"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08
      }
    },
    "/api/transit/route": {
      "get": {
        "summary": "Route Reliability Analysis",
        "description": "Is this route trustworthy for a time-sensitive trip? Reliability score, worst times, buffer to add. $0.08.",
        "operationId": "routeReliability",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "route",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Line or route name (e.g. L train, Northern line)"
          },
          {
            "name": "time",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Time of travel (e.g. 9am, rush hour)"
          }
        ],
        "responses": {
          "200": {
            "description": "Route reliability intelligence"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08
      }
    },
    "/api/transit/commute": {
      "get": {
        "summary": "Commute Quality Analysis",
        "description": "Commute intelligence for a specific corridor \u2014 options, peak-hour reality, cost, vs driving. $0.10.",
        "operationId": "commuteAnalysis",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Origin neighborhood or address"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Destination neighborhood or address"
          },
          {
            "name": "time",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "9am"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Commute quality analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    },
    "/api/transit/airport": {
      "get": {
        "summary": "Airport Transit Guide",
        "description": "Transit-to-airport feasibility, timing, fare, step-by-step options, vs-taxi comparison. $0.08.",
        "operationId": "airportTransit",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "airport",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "IATA code (JFK, LHR) or name"
          },
          {
            "name": "flight_time",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Flight departure time (e.g. 6am)"
          }
        ],
        "responses": {
          "200": {
            "description": "Airport transit guide"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08
      }
    },
    "/api/transit/agencies": {
      "get": {
        "summary": "Transit Agencies Lookup",
        "description": "All operators serving a city \u2014 what each runs, payment cards, coverage area. $0.05.",
        "operationId": "transitAgencies",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transit agencies and operators"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05
      }
    },
    "/api/transit/delays": {
      "get": {
        "summary": "Current Transit Delays",
        "description": "Active disruptions right now \u2014 affected lines, severity, and what to do. $0.05.",
        "operationId": "currentDelays",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "line",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current delay report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08
      }
    },
    "/api/transit/delays-history": {
      "get": {
        "summary": "Historical Delay Patterns",
        "description": "Reliability history \u2014 chronic issues, worst periods, trend direction, planning buffer. $0.08.",
        "operationId": "delayHistory",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "line",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical reliability analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/transit/trip": {
      "get": {
        "summary": "Transit Trip Planning",
        "description": "Step-by-step transit directions with timing, transfers, fare, and reliability rating. $0.10.",
        "operationId": "tripPlan",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "time",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trip plan with directions"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    },
    "/api/transit/multimodal": {
      "get": {
        "summary": "Multi-Modal Journey Planning",
        "description": "Optimized routing combining transit, bike, ferry, walking for most efficient journey. $0.10.",
        "operationId": "multimodalJourney",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "time",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Multi-modal journey plan"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/transit/compare": {
      "get": {
        "summary": "City-to-City Transit Comparison",
        "description": "Scored comparison across reliability, coverage, affordability, night service, airport access. $0.12.",
        "operationId": "cityComparison",
        "parameters": [
          {
            "name": "city_a",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "First city"
          },
          {
            "name": "city_b",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Second city"
          },
          {
            "name": "cities",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Alternative: comma-separated pair (e.g. NYC,London)"
          }
        ],
        "responses": {
          "200": {
            "description": "Scored city comparison"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    },
    "/api/transit/carfree": {
      "get": {
        "summary": "Car-Free Livability Score",
        "description": "Honest car-free living assessment \u2014 what works, what doesn't, daily scenarios, best neighborhoods. $0.12.",
        "operationId": "carFreeScore",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "neighborhood",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Car-free livability analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/transit/visitor": {
      "get": {
        "summary": "First-Timer Visitor Guide",
        "description": "What to do on arrival, payment setup, common mistakes, apps, night travel options. $0.08.",
        "operationId": "visitorGuide",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Visitor transit guide"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08
      }
    },
    "/api/transit/coverage": {
      "get": {
        "summary": "Transit Coverage Analysis",
        "description": "Transit desert mapping \u2014 strong areas, gaps, equity notes, planned expansions. $0.10.",
        "operationId": "coverageAnalysis",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transit coverage analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    }
  }
}