FindMagic Public API

FindMagic provides machine-readable endpoints so software agents, AI assistants, and developers can programmatically discover live magic performances and hire performers.

Quick Start

The FindMagic API is 100% free and unauthenticated. No API keys, OAuth tokens, or client secrets are required for read operations.

# Search for magicians in Chicago
curl -s "https://findmagic.show/api/v1/magicians?city=chicago"

# Get details on upcoming shows in Las Vegas
curl -s "https://findmagic.show/api/v1/shows?city=las-vegas"

# Autocomplete suggestions for search boxes
curl -s "https://findmagic.show/api/suggest.json?q=mentalism"

Machine Specifications & Catalogs

• OpenAPI 3.1.0 Specification: /openapi.json or /openapi.yaml
• RFC 9727 API Catalog: /.well-known/api-catalog
• Agentic Resource Discovery (ARD): /.well-known/ard.json and /.well-known/ai-catalog.json
• Authentication Policy: /auth.md (None required)
• Agent Site Map (llms.txt): /llms.txt

Endpoints Reference

1. GET /api/v1/magicians

Search and filter magicians. Supports free-text search, city filtering, specialty/genre filtering, and pagination.

• q (string, optional): Text search query across performer names, bio, and keywords.
• city (string, optional): City or metropolitan area slug (e.g. chicago, new-york, vancouver).
• genre (string, optional): Specialty slug (e.g. mentalism, close-up, comedy, stage).
• gigs (integer, optional): 1 to include performers available to travel to the city; 0 for local performers only.
• page (integer, optional, default: 1): Pagination page number.
• limit (integer, optional, default: 20, max: 100): Results per page.

2. GET /api/v1/magicians/{slug}

Retrieve full profile for a performer including biography, specialties, service area, website, upcoming shows, and verified reviews.

3. GET /api/v1/shows

List upcoming live magic shows, residencies, and tours.

• city (string, optional): City or metro slug (e.g. las-vegas).
• from (date YYYY-MM-DD, optional): Earliest date.
• to (date YYYY-MM-DD, optional): Latest date.
• limit (integer, optional, default: 50, max: 200): Max records returned.

4. GET /api/v1/shows/{slug}

Detailed show listing with venue information, scheduled run dates, and ticketing links.

5. GET /api/v1/venues

Directory of magic venues, theatres, and comedy clubs staging live magic.

6. GET /api/v1/cities

List of all metropolitan areas and cities covered by FindMagic with live show counts.

7. GET /api/suggest.json

Fast autocomplete suggestions across magicians, shows, and venues.

Error Handling (RFC 9457 Problem Details)

All API errors return structured JSON conforming to RFC 9457 Problem Details with Content-Type: application/problem+json. Each response contains the error type, title, status, code, human-readable detail, and an actionable resolution hint.

{
  "type": "https://findmagic.show/docs/errors#not_found",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "No performer found with slug 'nonexistent'",
  "instance": "/api/v1/magicians/nonexistent",
  "resolution": "Check the performer slug or search the directory at /api/v1/magicians."
}