---
title: FindMagic Public API Documentation
description: Free public directory API and OpenAPI 3.1 specification for live magic shows, magicians, venues, and cities.
canonical: https://findmagic.show/docs
last-updated: 2026-09-15
---

# FindMagic Public Directory API & Documentation

FindMagic provides a free, unauthenticated, open REST API for software agents and developers to search and retrieve live magic information.

## Specifications & Discovery

- [OpenAPI 3.1 Specification](https://findmagic.show/openapi.json)
- [OpenAPI YAML Specification](https://findmagic.show/openapi.yaml)
- [RFC 9727 API Catalog](https://findmagic.show/.well-known/api-catalog)
- [Agentic Resource Discovery (ARD)](https://findmagic.show/.well-known/ard.json)
- [Agent Guide (llms.txt)](https://findmagic.show/llms.txt)
- [Authentication Policy](https://findmagic.show/auth.md)

## Public API Endpoints (v1)

### 1. GET /api/v1/magicians
Search and filter magicians by name, city, specialty, and availability to travel.
Query Parameters:
- `q` (string): text search query
- `city` (string): city or metropolitan area slug (e.g. `chicago`, `new-york`)
- `genre` (string): specialty slug (e.g. `mentalism`, `close-up`, `comedy`)
- `gigs` (integer): `1` to include traveling magicians
- `page` (integer, default 1): page number
- `limit` (integer, default 20, max 100): items per page

### 2. GET /api/v1/magicians/{slug}
Retrieve comprehensive profile details for a performer.

### 3. GET /api/v1/shows
List upcoming live magic performances.
Query Parameters:
- `city` (string): city or metro slug
- `from` (string): earliest date in YYYY-MM-DD
- `to` (string): latest date in YYYY-MM-DD
- `limit` (integer, default 50, max 200)

### 4. GET /api/v1/shows/{slug}
Retrieve show details, venue, and scheduled run dates.

### 5. GET /api/v1/venues
List magic venues and theatres.

### 6. GET /api/v1/cities
List covered metropolitan areas with live show counts.

### 7. GET /api/suggest.json
Instant autocomplete search across magicians, shows, and venues.
Query Parameters:
- `q` (string, required): prefix search query (min 2 chars)

## Error Handling (RFC 9457)

All API errors return structured JSON Problem Details with `Content-Type: application/problem+json`.