API Documentation

Chicago comedy data for humans and AI agents. Free API, MCP server for AI tools, and machine-readable formats.

Free API

No authentication required. Limited to 50 requests per day per IP. All responses are JSON with Access-Control-Allow-Origin: *.

GET/api/showsfree

Upcoming comedy shows in Chicago. Returns future shows by default.

Param	Type	Default	Description
`limit`	1–200	50	Max results per page
`offset`	integer	0	Pagination offset
`venue_id`	UUID	—	Filter by venue
`comedian_slug`	string	—	Filter by comedian (e.g. john-mulaney)
`from`	ISO 8601	now	Start date/time
`to`	ISO 8601	—	End date/time
`free`	"true"	—	Only free shows (price_min = 0 or null)
`q`	string	—	Case-insensitive title search
`show_type`	string	—	standup, improv, open_mic, sketch, variety

Examples

curl https://chicagocomedy.org/api/shows?limit=5
curl "https://chicagocomedy.org/api/shows?free=true&show_type=open_mic"

Response

{
  "shows": [
    {
      "id": "uuid",
      "title": "Stand-Up Showcase",
      "starts_at": "2026-03-23T20:00:00Z",
      "price_min": 10,
      "show_type": "standup",
      "venues": { "name": "Zanies Chicago", "address": "..." }
    }
  ],
  "total": 142
}

GET/api/venuesfree

All comedy venues with location, neighborhood, and social links.

Param	Type	Default	Description
`neighborhood`	string	—	Filter by neighborhood (substring match)
`q`	string	—	Text search on venue name
`include_counts`	"true"	—	Add upcoming_show_count per venue

Examples

curl "https://chicagocomedy.org/api/venues?neighborhood=lincoln+park"

GET/api/comediansfree

Browse comedian profiles with social links.

Param	Type	Default	Description
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/searchfree

Text search across shows and venues.

Param	Type	Default	Description
`q`	string	required	Search query (min 2 chars)

GET/api/shows/nearbyfree

Shows near a geographic point.

Param	Type	Default	Description
`lat`	number	required	Latitude
`lng`	number	required	Longitude
`range`	string	tonight	Time range: tonight, weekend, week

MCP Server

ChicagoComedy.org exposes a Model Context Protocol (MCP) server, so AI tools like Claude Desktop, ChatGPT, Cursor, and others can query Chicago comedy data directly. Ask your AI assistant about comedy shows and it pulls real, live data from our database.

Claude Desktop — Quick Setup

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "chicagocomedy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://chicagocomedy.org/mcp"]
    }
  }
}

Restart Claude Desktop. You'll see a tools icon (🔌) confirming the connection. Then just ask naturally: "What comedy shows are in Chicago tonight?"

Any MCP-Compatible Client

Point any MCP client at the endpoint:

https://chicagocomedy.org/mcp

Supports the Streamable HTTP transport (stateless). No auth required.

Limits & Caching

To keep the public MCP endpoint reliable for everyone, requests are rate limited and short-term cached.

Rate limit: ~10 requests/minute per IP (with a small burst allowed).
Caching: responses may be cached for ~60 seconds to absorb bursts.
Higher-trust callers: if you control the client, you can include an internal header to bypass/relax limits:x-chicagocomedy-internal. (Requires a shared secret configured on the server.)

Available Tools

Tool	Description
`find_shows`	Find shows by date, type, neighborhood, and budget. The main tool — handles "what's funny tonight?"
`venue_info`	Look up a venue by name or neighborhood. Returns address, upcoming show count, and links.
`comedian_info`	Search for a comedian and see their upcoming shows in Chicago.
`search_comedy`	Full-text search across shows, venues, and comedians.
`comedy_stats`	Aggregate stats: shows this week, busiest nights, avg ticket price, venue counts.

The MCP server returns the same enriched data as the API — real shows, real venues, real ticket links. No hallucination, no stale training data.

Machine-Readable Formats

/mcp — MCP server endpoint (Streamable HTTP transport for AI tool integration)
/api/v1/openapi.json — OpenAPI 3.0 spec for the paid API (agent auto-discovery)
/llms.txt — Site overview for LLMs and AI agents
/llms-full.txt — Complete upcoming show listing (plain text)
/feed.xml — RSS feed of upcoming shows
Every page includes Schema.org JSON-LD (ComedyEvent, ComedyClub, Person)

Paid API (x402)

Enriched endpoints at /api/v1/*. Every request costs $0.001–$0.005 USDC on Base, paid via the x402 protocol. No API keys, no accounts — just pay per request.

OpenAPI spec: /api/v1/openapi.json

Endpoint	Price	What you get
`/api/v1/discover`	$0.001	Agent-optimized discovery with semantic filters + alternatives
`/api/v1/shows`	$0.001	Shows + performers, venue details, related shows
`/api/v1/shows/nearby`	$0.001	Geo-proximity with distance + performer details
`/api/v1/search`	$0.001	Full-text across shows, venues, comedians
`/api/v1/venues`	$0.001	Venue profiles + show frequency, price ranges, show types
`/api/v1/comedians`	$0.002	Comedian profiles + upcoming shows, venue history
`/api/v1/stats`	$0.005	Aggregate stats: busiest nights, avg prices, neighborhood data

GET/api/v1/discover$0.001 USDC

The headline endpoint for AI agents. Natural language-ish query parameters — no LLM calls, pure database queries with intelligent fallbacks.

Param	Type	Default	Description
`what`	string	any	standup, improv, open-mic, sketch, variety, any
`when`	string	tonight	tonight, tomorrow, this-weekend, this-week, YYYY-MM-DD
`where`	string	—	Neighborhood slug (e.g. wicker-park) or near:lat,lng
`budget`	string	any	free, under-10, under-20, under-50, any
`limit`	1–50	5	Max results

Examples

# Standup tonight
curl "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"

# Free shows this weekend in Wicker Park
curl "https://chicagocomedy.org/api/v1/discover?what=any&when=this-weekend&where=wicker-park&budget=free"

# Open mics this week near a location
curl "https://chicagocomedy.org/api/v1/discover?what=open-mic&when=this-week&where=near:41.91,-87.67"

Response

{
  "query_understood": "standup shows tonight in Chicago",
  "results": [
    {
      "id": "uuid",
      "title": "Stand-Up Showcase",
      "starts_at": "2026-03-23T20:00:00Z",
      "price_min": 15,
      "show_type": "standup",
      "performers": [
        { "name": "Jane Smith", "slug": "jane-smith", "role": "headliner" }
      ],
      "venue_details": {
        "name": "Zanies Chicago",
        "neighborhood": "Old Town",
        "address": "1548 N Wells St, Chicago, IL"
      }
    }
  ],
  "alternatives": null,
  "result_count": 1,
  "source": "chicagocomedy.org",
  "freshness": "2026-03-23T18:30:00Z"
}

When no results match, results is empty and alternatives suggests fallbacks (e.g. "3 improv shows available in this time range").

GET/api/v1/shows$0.001 USDC

Same filters as the free /api/shows, but returns enriched data: performer arrays, full venue objects, and related shows at the same venue/night.

Param	Type	Default	Description
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset
`venue_id`	UUID	—	Filter by venue
`comedian_slug`	string	—	Filter by comedian
`from`	ISO 8601	now	Start date/time
`to`	ISO 8601	—	End date/time
`free`	"true"	—	Only free shows
`q`	string	—	Title search
`show_type`	string	—	standup, improv, open_mic, sketch, variety

GET/api/v1/shows/nearby$0.001 USDC

Geo-proximity search with distance in miles and performer details.

Param	Type	Default	Description
`lat`	number	required	Latitude
`lng`	number	required	Longitude
`range`	string	tonight	tonight, weekend, week
`radius_miles`	number	5	Search radius (max 50)

GET/api/v1/search$0.001 USDC

Full-text search across shows, venues, and comedians with enriched results.

Param	Type	Default	Description
`q`	string	required	Search query (min 2 chars)
`limit`	1–50	15	Max results per category

GET/api/v1/venues$0.001 USDC

Venue profiles enriched with show frequency, typical price ranges, and show type distribution.

Param	Type	Default	Description
`neighborhood`	string	—	Filter by neighborhood
`venue_type`	string	—	Filter by venue type
`q`	string	—	Text search on name
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/v1/comedians$0.002 USDC

Comedian profiles with upcoming shows, venue history, and show frequency.

Param	Type	Default	Description
`q`	string	—	Search by name
`slug`	string	—	Filter by exact slug
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/v1/stats$0.005 USDC

Aggregate Chicago comedy statistics — the data nobody else has.

Response

{
  "shows_this_week": {
    "total": 187,
    "by_type": { "standup": 62, "improv": 48, "open_mic": 41, "sketch": 12, "variety": 24 }
  },
  "busiest_nights": [
    { "day": "Saturday", "show_count": 42 },
    { "day": "Friday", "show_count": 38 }
  ],
  "avg_ticket_prices": { "standup": 18.50, "improv": 22.00, "open_mic": 0 },
  "venues_by_neighborhood": { "Lincoln Park": 12, "Old Town": 8, "Wicker Park": 7 },
  "totals": { "venues": 97, "comedians": 241, "upcoming_shows": 187 }
}

How x402 Works

x402 is an open protocol for HTTP-native micropayments. It uses HTTP status code 402 Payment Required — the status code the web reserved for payments since 1999 but never used. Until now.

Request: Your agent calls a paid endpoint (e.g. GET /api/v1/discover?what=standup).

402 Response: The server responds with 402 Payment Required and a JSON body describing the price, network (Base), and wallet address.

Payment: Your agent signs a USDC payment on Base and retries the request with an X-Payment header containing the signed transaction.

Data: The server verifies payment via a facilitator and returns the enriched data. The USDC settles on Base.

TypeScript — @x402/fetch (recommended)

The easiest way to interact with x402 APIs. One import wraps standard fetch with automatic payment handling:

import { wrapFetch } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

const wallet = createWalletClient({
  chain: base,
  transport: http(),
  account: yourPrivateKey,
});

const fetchWithPay = wrapFetch(fetch, wallet);

// That's it — calls automatically handle 402 → pay → retry
const res = await fetchWithPay(
  "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"
);
const data = await res.json();

Python — x402

Install with pip install "x402[httpx]" (async) or pip install "x402[requests]" (sync):

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner
from x402 import x402Client
from x402.httpx import wrap_httpx_with_payment
import httpx

# Create signer from private key
account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

# Create x402 client
client = x402Client()
client.register_evm_scheme(signer=signer)

# Wrap httpx — automatic 402 → pay → retry
http = wrap_httpx_with_payment(httpx.Client(), client)

response = http.get(
    "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"
)
data = response.json()
print(data["results"])

Cost at scale

$1 = 1,000 queries at $0.001/each
$5 = enough for 5,000 agent queries
Base L2 transaction fees are sub-penny, so micropayments actually work

Loading shows…

API Documentation

Chicago comedy data for humans and AI agents. Free API, MCP server for AI tools, and machine-readable formats.

Free API

No authentication required. Limited to 50 requests per day per IP. All responses are JSON with Access-Control-Allow-Origin: *.

GET/api/showsfree

Upcoming comedy shows in Chicago. Returns future shows by default.

Param	Type	Default	Description
`limit`	1–200	50	Max results per page
`offset`	integer	0	Pagination offset
`venue_id`	UUID	—	Filter by venue
`comedian_slug`	string	—	Filter by comedian (e.g. john-mulaney)
`from`	ISO 8601	now	Start date/time
`to`	ISO 8601	—	End date/time
`free`	"true"	—	Only free shows (price_min = 0 or null)
`q`	string	—	Case-insensitive title search
`show_type`	string	—	standup, improv, open_mic, sketch, variety

Examples

curl https://chicagocomedy.org/api/shows?limit=5
curl "https://chicagocomedy.org/api/shows?free=true&show_type=open_mic"

Response

{
  "shows": [
    {
      "id": "uuid",
      "title": "Stand-Up Showcase",
      "starts_at": "2026-03-23T20:00:00Z",
      "price_min": 10,
      "show_type": "standup",
      "venues": { "name": "Zanies Chicago", "address": "..." }
    }
  ],
  "total": 142
}

GET/api/venuesfree

All comedy venues with location, neighborhood, and social links.

Param	Type	Default	Description
`neighborhood`	string	—	Filter by neighborhood (substring match)
`q`	string	—	Text search on venue name
`include_counts`	"true"	—	Add upcoming_show_count per venue

Examples

curl "https://chicagocomedy.org/api/venues?neighborhood=lincoln+park"

GET/api/comediansfree

Browse comedian profiles with social links.

Param	Type	Default	Description
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/searchfree

Text search across shows and venues.

Param	Type	Default	Description
`q`	string	required	Search query (min 2 chars)

GET/api/shows/nearbyfree

Shows near a geographic point.

Param	Type	Default	Description
`lat`	number	required	Latitude
`lng`	number	required	Longitude
`range`	string	tonight	Time range: tonight, weekend, week

MCP Server

Claude Desktop — Quick Setup

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "chicagocomedy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://chicagocomedy.org/mcp"]
    }
  }
}

Restart Claude Desktop. You'll see a tools icon (🔌) confirming the connection. Then just ask naturally: "What comedy shows are in Chicago tonight?"

Any MCP-Compatible Client

Point any MCP client at the endpoint:

https://chicagocomedy.org/mcp

Supports the Streamable HTTP transport (stateless). No auth required.

Limits & Caching

To keep the public MCP endpoint reliable for everyone, requests are rate limited and short-term cached.

Rate limit: ~10 requests/minute per IP (with a small burst allowed).
Caching: responses may be cached for ~60 seconds to absorb bursts.
Higher-trust callers: if you control the client, you can include an internal header to bypass/relax limits:x-chicagocomedy-internal. (Requires a shared secret configured on the server.)

Available Tools

Tool	Description
`find_shows`	Find shows by date, type, neighborhood, and budget. The main tool — handles "what's funny tonight?"
`venue_info`	Look up a venue by name or neighborhood. Returns address, upcoming show count, and links.
`comedian_info`	Search for a comedian and see their upcoming shows in Chicago.
`search_comedy`	Full-text search across shows, venues, and comedians.
`comedy_stats`	Aggregate stats: shows this week, busiest nights, avg ticket price, venue counts.

The MCP server returns the same enriched data as the API — real shows, real venues, real ticket links. No hallucination, no stale training data.

Machine-Readable Formats

/mcp — MCP server endpoint (Streamable HTTP transport for AI tool integration)
/api/v1/openapi.json — OpenAPI 3.0 spec for the paid API (agent auto-discovery)
/llms.txt — Site overview for LLMs and AI agents
/llms-full.txt — Complete upcoming show listing (plain text)
/feed.xml — RSS feed of upcoming shows
Every page includes Schema.org JSON-LD (ComedyEvent, ComedyClub, Person)

Paid API (x402)

Enriched endpoints at /api/v1/*. Every request costs $0.001–$0.005 USDC on Base, paid via the x402 protocol. No API keys, no accounts — just pay per request.

OpenAPI spec: /api/v1/openapi.json

Endpoint	Price	What you get
`/api/v1/discover`	$0.001	Agent-optimized discovery with semantic filters + alternatives
`/api/v1/shows`	$0.001	Shows + performers, venue details, related shows
`/api/v1/shows/nearby`	$0.001	Geo-proximity with distance + performer details
`/api/v1/search`	$0.001	Full-text across shows, venues, comedians
`/api/v1/venues`	$0.001	Venue profiles + show frequency, price ranges, show types
`/api/v1/comedians`	$0.002	Comedian profiles + upcoming shows, venue history
`/api/v1/stats`	$0.005	Aggregate stats: busiest nights, avg prices, neighborhood data

GET/api/v1/discover$0.001 USDC

The headline endpoint for AI agents. Natural language-ish query parameters — no LLM calls, pure database queries with intelligent fallbacks.

Param	Type	Default	Description
`what`	string	any	standup, improv, open-mic, sketch, variety, any
`when`	string	tonight	tonight, tomorrow, this-weekend, this-week, YYYY-MM-DD
`where`	string	—	Neighborhood slug (e.g. wicker-park) or near:lat,lng
`budget`	string	any	free, under-10, under-20, under-50, any
`limit`	1–50	5	Max results

Examples

# Standup tonight
curl "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"

# Free shows this weekend in Wicker Park
curl "https://chicagocomedy.org/api/v1/discover?what=any&when=this-weekend&where=wicker-park&budget=free"

# Open mics this week near a location
curl "https://chicagocomedy.org/api/v1/discover?what=open-mic&when=this-week&where=near:41.91,-87.67"

Response

{
  "query_understood": "standup shows tonight in Chicago",
  "results": [
    {
      "id": "uuid",
      "title": "Stand-Up Showcase",
      "starts_at": "2026-03-23T20:00:00Z",
      "price_min": 15,
      "show_type": "standup",
      "performers": [
        { "name": "Jane Smith", "slug": "jane-smith", "role": "headliner" }
      ],
      "venue_details": {
        "name": "Zanies Chicago",
        "neighborhood": "Old Town",
        "address": "1548 N Wells St, Chicago, IL"
      }
    }
  ],
  "alternatives": null,
  "result_count": 1,
  "source": "chicagocomedy.org",
  "freshness": "2026-03-23T18:30:00Z"
}

When no results match, results is empty and alternatives suggests fallbacks (e.g. "3 improv shows available in this time range").

GET/api/v1/shows$0.001 USDC

Same filters as the free /api/shows, but returns enriched data: performer arrays, full venue objects, and related shows at the same venue/night.

Param	Type	Default	Description
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset
`venue_id`	UUID	—	Filter by venue
`comedian_slug`	string	—	Filter by comedian
`from`	ISO 8601	now	Start date/time
`to`	ISO 8601	—	End date/time
`free`	"true"	—	Only free shows
`q`	string	—	Title search
`show_type`	string	—	standup, improv, open_mic, sketch, variety

GET/api/v1/shows/nearby$0.001 USDC

Geo-proximity search with distance in miles and performer details.

Param	Type	Default	Description
`lat`	number	required	Latitude
`lng`	number	required	Longitude
`range`	string	tonight	tonight, weekend, week
`radius_miles`	number	5	Search radius (max 50)

GET/api/v1/search$0.001 USDC

Full-text search across shows, venues, and comedians with enriched results.

Param	Type	Default	Description
`q`	string	required	Search query (min 2 chars)
`limit`	1–50	15	Max results per category

GET/api/v1/venues$0.001 USDC

Venue profiles enriched with show frequency, typical price ranges, and show type distribution.

Param	Type	Default	Description
`neighborhood`	string	—	Filter by neighborhood
`venue_type`	string	—	Filter by venue type
`q`	string	—	Text search on name
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/v1/comedians$0.002 USDC

Comedian profiles with upcoming shows, venue history, and show frequency.

Param	Type	Default	Description
`q`	string	—	Search by name
`slug`	string	—	Filter by exact slug
`limit`	1–200	50	Max results
`offset`	integer	0	Pagination offset

GET/api/v1/stats$0.005 USDC

Aggregate Chicago comedy statistics — the data nobody else has.

Response

{
  "shows_this_week": {
    "total": 187,
    "by_type": { "standup": 62, "improv": 48, "open_mic": 41, "sketch": 12, "variety": 24 }
  },
  "busiest_nights": [
    { "day": "Saturday", "show_count": 42 },
    { "day": "Friday", "show_count": 38 }
  ],
  "avg_ticket_prices": { "standup": 18.50, "improv": 22.00, "open_mic": 0 },
  "venues_by_neighborhood": { "Lincoln Park": 12, "Old Town": 8, "Wicker Park": 7 },
  "totals": { "venues": 97, "comedians": 241, "upcoming_shows": 187 }
}

How x402 Works

x402 is an open protocol for HTTP-native micropayments. It uses HTTP status code 402 Payment Required — the status code the web reserved for payments since 1999 but never used. Until now.

Request: Your agent calls a paid endpoint (e.g. GET /api/v1/discover?what=standup).

402 Response: The server responds with 402 Payment Required and a JSON body describing the price, network (Base), and wallet address.

Payment: Your agent signs a USDC payment on Base and retries the request with an X-Payment header containing the signed transaction.

Data: The server verifies payment via a facilitator and returns the enriched data. The USDC settles on Base.

TypeScript — @x402/fetch (recommended)

The easiest way to interact with x402 APIs. One import wraps standard fetch with automatic payment handling:

import { wrapFetch } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

const wallet = createWalletClient({
  chain: base,
  transport: http(),
  account: yourPrivateKey,
});

const fetchWithPay = wrapFetch(fetch, wallet);

// That's it — calls automatically handle 402 → pay → retry
const res = await fetchWithPay(
  "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"
);
const data = await res.json();

Python — x402

Install with pip install "x402[httpx]" (async) or pip install "x402[requests]" (sync):

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner
from x402 import x402Client
from x402.httpx import wrap_httpx_with_payment
import httpx

# Create signer from private key
account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

# Create x402 client
client = x402Client()
client.register_evm_scheme(signer=signer)

# Wrap httpx — automatic 402 → pay → retry
http = wrap_httpx_with_payment(httpx.Client(), client)

response = http.get(
    "https://chicagocomedy.org/api/v1/discover?what=standup&when=tonight"
)
data = response.json()
print(data["results"])

Cost at scale

$1 = 1,000 queries at $0.001/each
$5 = enough for 5,000 agent queries
Base L2 transaction fees are sub-penny, so micropayments actually work