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