{"openapi":"3.1.0","info":{"title":"FindMagic Public Directory API","version":"1.0.0","description":"Free public directory API for discovering live magic shows and finding magicians to hire. FindMagic charges no listing fees, lead fees, or booking commissions, and requires no API key or authentication.","termsOfService":"https://findmagic.show/terms","contact":{"name":"FindMagic Support","url":"https://findmagic.show/contact","email":"hello@findmagic.show"},"license":{"name":"CC0 1.0 Universal / Public Domain","url":"https://creativecommons.org/publicdomain/zero/1.0/"}},"servers":[{"url":"https://findmagic.show","description":"FindMagic production server"}],"paths":{"/api/v1/magicians":{"get":{"operationId":"searchMagicians","summary":"Search and filter magician directory","description":"Search magicians by text query, city/metro slug, specialty/genre, or whether they travel for gigs.","tags":["Magicians"],"parameters":[{"name":"q","in":"query","description":"Search query by performer name, keyword, or biography","required":false,"schema":{"type":"string"}},{"name":"city","in":"query","description":"City or metropolitan area slug (e.g. 'chicago', 'new-york', 'vancouver')","required":false,"schema":{"type":"string"}},{"name":"genre","in":"query","description":"Specialty or performance style slug (e.g. 'mentalism', 'close-up', 'comedy', 'stage')","required":false,"schema":{"type":"string"}},{"name":"gigs","in":"query","description":"1 to find performers available to travel to the specified city, 0 for locally based only","required":false,"schema":{"type":"integer","enum":[0,1],"default":0}},{"name":"page","in":"query","description":"Pagination page number (1-indexed)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Number of results to return per page (maximum 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Paginated list of magicians matching search criteria","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of magicians matching criteria"},"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MagicianSummary"},"description":"List of magician cards"}},"required":["total","page","limit","items"]}}}},"400":{"description":"Invalid search parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/magicians/{slug}":{"get":{"operationId":"getMagicianBySlug","summary":"Get magician profile by slug","description":"Retrieve comprehensive details for a magician including biography, service area, specialties, verified reviews, upcoming shows, and direct contact routes.","tags":["Magicians"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Unique slug identifier for the magician (e.g. 'shin-lim', 'david-copperfield')","schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed magician profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicianProfile"}}}},"404":{"description":"Magician not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/shows":{"get":{"operationId":"listShows","summary":"List upcoming live magic shows","description":"Find upcoming live magic performances, residencies, and tours filtered by city and date range.","tags":["Shows"],"parameters":[{"name":"city","in":"query","description":"Filter shows by city or metropolitan area slug (e.g. 'las-vegas', 'new-york', 'london')","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","description":"Earliest show date in YYYY-MM-DD format (defaults to current date)","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Latest show date in YYYY-MM-DD format","required":false,"schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Maximum number of show items to return (maximum 200)","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"List of upcoming shows","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Number of upcoming shows returned"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ShowSummary"},"description":"List of show listings"}},"required":["total","items"]}}}},"400":{"description":"Invalid date or city filter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/shows/{slug}":{"get":{"operationId":"getShowBySlug","summary":"Get magic show details by slug","description":"Retrieve detailed information for a magic show including venue details, scheduled dates, and direct ticketing links.","tags":["Shows"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Show slug identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed show information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowDetail"}}}},"404":{"description":"Show not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/venues":{"get":{"operationId":"listVenues","summary":"List magic venues and theatres","description":"List magic theatres, clubs, and venues that regularly host live magic performances.","tags":["Venues"],"parameters":[{"name":"city","in":"query","description":"Filter venues by city or metropolitan area slug","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of venues to return (maximum 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"List of magic venues","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total venues returned"},"items":{"type":"array","items":{"$ref":"#/components/schemas/VenueSummary"}}},"required":["total","items"]}}}}}}},"/api/v1/cities":{"get":{"operationId":"listCities","summary":"List covered cities and metropolitan areas","description":"List metropolitan areas and cities covered by FindMagic with live show counts and geographical info.","tags":["Cities"],"responses":{"200":{"description":"List of cities with active magic scenes","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CitySummary"}}},"required":["total","items"]}}}}}}},"/api/suggest.json":{"get":{"operationId":"suggestEntities","summary":"Autocomplete suggestions for magicians, shows, and venues","description":"Instant autocomplete suggestions across magicians, shows, and venues for search dropdowns.","tags":["Discovery"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search prefix query (e.g. 'dav' or 'mag')","schema":{"type":"string"}}],"responses":{"200":{"description":"Autocomplete suggestions grouped by entity kind","content":{"application/json":{"schema":{"type":"object","properties":{"magicians":{"type":"array","items":{"$ref":"#/components/schemas/SuggestionItem"}},"shows":{"type":"array","items":{"$ref":"#/components/schemas/SuggestionItem"}},"venues":{"type":"array","items":{"$ref":"#/components/schemas/SuggestionItem"}}}}}}}}}}},"components":{"schemas":{"MagicianSummary":{"type":"object","description":"Summary card of a magician performer","properties":{"slug":{"type":"string","description":"Performer unique slug"},"name":{"type":"string","description":"Performer stage name"},"city":{"type":"string","nullable":true,"description":"Home metropolitan area or base city"},"tagline":{"type":"string","nullable":true,"description":"Short descriptive headline or hook"},"bio":{"type":"string","nullable":true,"description":"Editorial or claimed biography snippet"},"specialties":{"type":"array","items":{"type":"string"},"description":"Primary performance specialties (e.g. mentalism, close-up, comedy)"},"profile_url":{"type":"string","format":"uri","description":"Canonical profile URL on FindMagic"},"image_url":{"type":"string","format":"uri","nullable":true,"description":"Portrait or headshot URL"},"claimed":{"type":"boolean","description":"Whether the profile has been verified and claimed by the performer"},"public_dates_count":{"type":"integer","description":"Count of upcoming public live performances"}},"required":["slug","name","specialties","profile_url","claimed"]},"MagicianProfile":{"type":"object","description":"Complete magician profile with biography, media, reviews, and booking details","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":"string","nullable":true},"tagline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"specialties":{"type":"array","items":{"type":"string"}},"profile_url":{"type":"string","format":"uri"},"image_url":{"type":"string","format":"uri","nullable":true},"claimed":{"type":"boolean"},"website":{"type":"string","format":"uri","nullable":true},"booking_url":{"type":"string","format":"uri","nullable":true},"social_links":{"type":"object","additionalProperties":{"type":"string"}},"upcoming_shows":{"type":"array","items":{"$ref":"#/components/schemas/ShowSummary"}},"reviews_count":{"type":"integer"},"rating":{"type":"number","nullable":true}},"required":["slug","name","specialties","profile_url","claimed"]},"ShowSummary":{"type":"object","description":"Summary of an upcoming live magic show or residency","properties":{"slug":{"type":"string","description":"Show slug identifier"},"title":{"type":"string","description":"Show title"},"venue_name":{"type":"string","nullable":true,"description":"Venue or theatre name"},"city":{"type":"string","nullable":true,"description":"City or metropolitan area"},"dates_count":{"type":"integer","description":"Number of upcoming dates"},"next_date":{"type":"string","format":"date","nullable":true,"description":"Earliest upcoming date in YYYY-MM-DD"},"ticket_url":{"type":"string","format":"uri","nullable":true,"description":"Direct ticketing link"},"url":{"type":"string","format":"uri","description":"Canonical URL on FindMagic"}},"required":["slug","title","url"]},"ShowDetail":{"type":"object","description":"Comprehensive show information including schedule and lineup","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"venue":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}}},"dates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"time":{"type":"string","nullable":true},"ticket_url":{"type":"string","format":"uri","nullable":true}}}},"ticket_url":{"type":"string","format":"uri","nullable":true},"url":{"type":"string","format":"uri"}},"required":["slug","title","url"]},"VenueSummary":{"type":"object","description":"Magic venue or theatre listing","properties":{"slug":{"type":"string"},"name":{"type":"string"},"city":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"shows_count":{"type":"integer","description":"Active upcoming shows at this venue"},"url":{"type":"string","format":"uri"}},"required":["slug","name","url"]},"CitySummary":{"type":"object","description":"Metropolitan area covered by FindMagic","properties":{"slug":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"country":{"type":"string","nullable":true},"shows_count":{"type":"integer","description":"Number of upcoming shows in this market"},"url":{"type":"string","format":"uri"}},"required":["slug","name","display_name","url"]},"SuggestionItem":{"type":"object","properties":{"title":{"type":"string"},"subtitle":{"type":"string","nullable":true},"url":{"type":"string"},"type":{"type":"string","enum":["magician","show","venue"]}},"required":["title","url","type"]},"ProblemDetails":{"type":"object","description":"RFC 9457 Problem Details error response","properties":{"type":{"type":"string","format":"uri","description":"URI reference identifying the error type"},"title":{"type":"string","description":"Short human-readable summary of the problem type"},"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Machine-readable application error code"},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence of the problem"},"instance":{"type":"string","description":"URI reference identifying the specific occurrence of the problem"},"resolution":{"type":"string","description":"Actionable guidance on how an agent or client can resolve the error"}},"required":["type","title","status","code","detail","resolution"]}}}}