{
  "openapi": "3.1.0",
  "info": {
    "title": "foundercal events API",
    "version": "1.0.0",
    "summary": "Read-only startup and founder events by city",
    "description": "Curated startup and founder events (conferences, demo days, founder dinners, meetups, hackathons, workshops) per city. Free, no authentication, read-only. Human and agent usage guide: https://foundercal.com/llms.txt",
    "contact": {
      "name": "foundercal",
      "url": "https://foundercal.com/contact",
      "email": "hello@lukasvonkunhardt.com"
    }
  },
  "servers": [
    {
      "url": "https://foundercal.com"
    }
  ],
  "paths": {
    "/api/events.json": {
      "get": {
        "operationId": "listEvents",
        "summary": "List upcoming events for a city",
        "description": "Returns upcoming curated events for one city, soonest first. Without the city parameter it returns a discovery document (usage plus all valid city slugs). An unknown parameter value returns HTTP 400 with the same usage help.",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "City slug, for example 'berlin', 'sf', 'nyc'. Omit to receive a discovery document listing all valid city slugs (also in https://foundercal.com/llms.txt).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Event type. Accepts the canonical value or its URL-slug plural (for example 'meetup' or 'meetups').",
            "schema": {
              "type": "string",
              "enum": [
                "meetup",
                "conference",
                "demo_day",
                "hackathon",
                "pitch",
                "workshop",
                "dinner"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of events to return (1-200).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Upcoming events for the city",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter, with usage help",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventList": {
        "type": "object",
        "required": [
          "city",
          "count",
          "events"
        ],
        "properties": {
          "city": {
            "type": "string"
          },
          "type": {
            "type": [
              "string",
              "null"
            ]
          },
          "count": {
            "type": "integer"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "title",
          "type",
          "city",
          "start_at",
          "tz",
          "event_url"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "meetup",
              "conference",
              "demo_day",
              "hackathon",
              "pitch",
              "workshop",
              "dinner"
            ]
          },
          "city": {
            "type": "string"
          },
          "start_at": {
            "type": "string",
            "format": "date-time"
          },
          "end_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "tz": {
            "type": "string",
            "description": "IANA timezone of the event"
          },
          "venue": {
            "type": [
              "string",
              "null"
            ]
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "is_free": {
            "type": "boolean"
          },
          "price_min": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Minor currency units (cents)"
          },
          "price_max": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "organizer": {
            "type": [
              "string",
              "null"
            ]
          },
          "organizer_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "event_url": {
            "type": "string",
            "format": "uri",
            "description": "The foundercal event page (canonical, citable)"
          },
          "register_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Official registration page of the organizer"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "UsageError": {
        "type": "object",
        "required": [
          "error",
          "usage"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          },
          "valid_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "valid_cities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}