{
  "openapi": "3.1.0",
  "info": {
    "title": "SXSW 2026 Schedule API",
    "description": "Query the SXSW 2026 festival schedule. All 2790 events across March 12–18, 2026. Data refreshed daily from schedule.sxsw.com.",
    "version": "1.0.0",
    "x-agents-json": "https://sxsw.0fn.net/agents.json",
    "x-llms-txt": "https://sxsw.0fn.net/llms.txt"
  },
  "servers": [
    {
      "url": "https://sxsw.0fn.net/api",
      "description": "SXSW 2026 Schedule API"
    }
  ],
  "x-example-urls": [
    "https://sxsw.0fn.net/api/health",
    "https://sxsw.0fn.net/api/dates",
    "https://sxsw.0fn.net/api/events?date=2026-03-14&q=AI&q_mode=any&limit=50",
    "https://sxsw.0fn.net/api/events?date=2026-03-14&q=AI+developer+tooling&q_mode=all&limit=50",
    "https://sxsw.0fn.net/api/shortlist?topic=ai-developer-tooling&per_day=5"
  ],
  "paths": {
    "/events": {
      "get": {
        "operationId": "searchEvents",
        "summary": "Search and filter events",
        "description": "Returns events matching all supplied filters. All params optional and combinable. NOTE: 'category' is a format label (Panel, Rock, Mentor Session, etc.) — use 'q' for topic search. q_mode controls token behavior (any/all/phrase). Results paginated (default 50, max 200).",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "2026-03-14"
            },
            "description": "Festival date (YYYY-MM-DD). One of: 2026-03-12 through 2026-03-18."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Mentor Session"
            },
            "description": "Partial match on category (case-insensitive). Category is a format label: Panel, Rock, Mentor Session, Presentation, Documentary Feature, etc. Use /api/categories for the full list. Use 'q' for topic-based search."
          },
          {
            "name": "venue",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Hilton"
            },
            "description": "Partial match on venue name (case-insensitive)."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "panel",
                "showcase",
                "screening",
                "networking",
                "party",
                "activation",
                "exhibition",
                "comedy_event",
                "lounge",
                "special_event",
                "registration"
              ]
            },
            "description": "Exact match on event_type."
          },
          {
            "name": "contributor",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Carmen Simon"
            },
            "description": "Partial match on contributor/speaker/artist name."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "artificial intelligence developer tooling"
            },
            "description": "Full-text search across event name, category, venue, and contributor names. Tokenized with synonym normalization."
          },
          {
            "name": "q_mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "all",
                "phrase"
              ],
              "default": "any"
            },
            "description": "Search mode: any token, all tokens, or phrase match."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Max results to return."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pagination offset."
          }
        ],
        "x-agent-example-url": "https://sxsw.0fn.net/api/events?date=2026-03-14&q=AI&q_mode=any&limit=50",
        "responses": {
          "200": {
            "description": "Matching events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                },
                "examples": {
                  "aiAny": {
                    "summary": "Broad AI topic search",
                    "value": {
                      "total": 48,
                      "offset": 0,
                      "limit": 50,
                      "count": 50,
                      "results": [
                        {
                          "event_id": "PP1162244",
                          "name": "The New Lab Partner: AI and Future Scientific Discovery",
                          "date": "2026-03-14",
                          "event_type": "panel",
                          "official_url": "https://schedule.sxsw.com/2026/events/PP1162244",
                          "score": 11,
                          "matched_terms": [
                            "ai"
                          ],
                          "matched_fields": [
                            "name"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shortlist": {
      "get": {
        "operationId": "getShortlist",
        "summary": "Get ranked top sessions per day for a topic",
        "description": "Single-call endpoint optimized for agent workflows. Returns ranked sessions by day with event_id and official_url in each item.",
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "ai-developer-tooling",
              "default": "ai-developer-tooling"
            },
            "description": "Preset topic slug. Unknown values are treated as custom topic text."
          },
          {
            "name": "per_day",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 20
            },
            "description": "Number of sessions to return per date."
          }
        ],
        "x-agent-example-url": "https://sxsw.0fn.net/api/shortlist?topic=ai-developer-tooling&per_day=5",
        "responses": {
          "200": {
            "description": "Ranked daily shortlist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShortlistResponse"
                }
              }
            }
          }
        }
      }
    },
    "/events/{event_id}": {
      "get": {
        "operationId": "getEvent",
        "summary": "Get a single event by ID",
        "parameters": [
          {
            "name": "event_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "PP1162244"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health and index freshness info",
        "description": "Returns service health, current event count, and index timestamp from the loaded schedule snapshot.",
        "x-agent-example-url": "https://sxsw.0fn.net/api/health",
        "responses": {
          "200": {
            "description": "Health status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/dates": {
      "get": {
        "operationId": "getDates",
        "summary": "List all festival dates with event counts",
        "x-agent-example-url": "https://sxsw.0fn.net/api/dates",
        "responses": {
          "200": {
            "description": "Date list"
          }
        }
      }
    },
    "/venues": {
      "get": {
        "operationId": "getVenues",
        "summary": "List venues, optionally filtered by name",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Hilton"
            },
            "description": "Partial match on venue name."
          }
        ],
        "x-agent-example-url": "https://sxsw.0fn.net/api/venues?name=Hilton",
        "responses": {
          "200": {
            "description": "Venue list with event counts"
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "getCategories",
        "summary": "List all event categories with counts",
        "x-agent-example-url": "https://sxsw.0fn.net/api/categories",
        "responses": {
          "200": {
            "description": "Category list"
          }
        }
      }
    },
    "/contributors": {
      "get": {
        "operationId": "searchContributors",
        "summary": "Find speakers, artists, or performers by name",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Carmen Simon"
            },
            "description": "Partial match on contributor name."
          }
        ],
        "x-agent-example-url": "https://sxsw.0fn.net/api/contributors?name=Carmen+Simon",
        "responses": {
          "200": {
            "description": "Matching contributors with their events"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Event": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "event_type": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "reservable": {
            "type": "boolean"
          },
          "official_url": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number",
            "description": "Search relevance score (present when q is provided)."
          },
          "matched_terms": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Canonical query terms matched for this event (present when q is provided)."
          },
          "matched_fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Event fields where query matches were found (present when q is provided)."
          },
          "credentials": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "status": {
            "type": "string"
          },
          "venue": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "lat": {
                "type": "number"
              },
              "lon": {
                "type": "number"
              }
            }
          },
          "contributors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EventList": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          }
        }
      },
      "ShortlistItem": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "event_type": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "official_url": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number"
          },
          "matched_terms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "matched_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ShortlistDay": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "query_used": {
            "type": "string"
          },
          "q_mode_used": {
            "type": "string"
          },
          "total_candidates": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShortlistItem"
            }
          }
        }
      },
      "ShortlistResponse": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string"
          },
          "topic_label": {
            "type": "string"
          },
          "per_day": {
            "type": "integer"
          },
          "festival_year": {
            "type": "integer"
          },
          "index_timestamp": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "days": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShortlistDay"
            }
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "festival_year": {
            "type": "integer"
          },
          "event_count": {
            "type": "integer"
          },
          "index_timestamp": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "cache_ttl_seconds": {
            "type": "integer"
          },
          "source_feed": {
            "type": "string",
            "format": "uri"
          },
          "now": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}