> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entertheatre.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Overview of the Enter Theatre API

## Overview

The Enter Theatre API provides programmatic access to West End theatre data. This RESTful API allows you to retrieve, create, update, and delete information about shows, theatres, people, productions, cast members, and roles.

## Base URL

```
https://entertheatre.com/api
```

## Available Resources

| Resource                                         | Description                                       |
| ------------------------------------------------ | ------------------------------------------------- |
| [Shows](/api-reference/shows/list)               | Theatre shows (musicals, plays, comedies, dramas) |
| [Theatres](/api-reference/theatres/list)         | West End venue information                        |
| [People](/api-reference/people/list)             | Performers and crew members                       |
| [Productions](/api-reference/productions/list)   | Show runs at specific theatres                    |
| [Cast Members](/api-reference/cast-members/list) | People linked to productions                      |
| [Roles](/api-reference/roles/list)               | Character definitions                             |

## HTTP Methods

| Method   | Description                                   |
| -------- | --------------------------------------------- |
| `GET`    | Retrieve resources (public, no auth required) |
| `POST`   | Create new resources (requires auth)          |
| `PUT`    | Update existing resources (requires auth)     |
| `DELETE` | Remove resources (requires auth)              |

## Request Format

For `POST` and `PUT` requests, send JSON data with the `Content-Type: application/json` header:

```bash theme={null}
curl -X POST https://entertheatre.com/api/shows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "New Musical",
    "type": "musical",
    "description": "A brand new West End show"
  }'
```

## Response Format

### Success Responses

Successful requests return JSON data:

```json theme={null}
{
  "id": "abc123",
  "name": "Hamilton",
  "type": "musical",
  "description": "The story of America's founding father",
  "image": "https://example.com/hamilton.jpg",
  "booking_until": "2025-12-31"
}
```

List endpoints return arrays:

```json theme={null}
[
  { "id": "abc123", "name": "Hamilton", ... },
  { "id": "def456", "name": "Wicked", ... }
]
```

### Error Responses

Errors return a JSON object with an error message:

```json theme={null}
{
  "error": "Show not found"
}
```

## HTTP Status Codes

| Code  | Description                    |
| ----- | ------------------------------ |
| `200` | Success                        |
| `201` | Created (for POST requests)    |
| `400` | Bad request (invalid data)     |
| `401` | Unauthorized (invalid API key) |
| `404` | Resource not found             |
| `429` | Rate limit exceeded            |
| `500` | Server error                   |

## Rate Limiting

All API requests are rate-limited:

| Access Level        | Limit               |
| ------------------- | ------------------- |
| Public (no API key) | 100 requests/day    |
| With API key        | 10,000 requests/day |

Every response includes rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1701388800
```

Get an API key from [entertheatre.com/dashboard/api-keys](https://entertheatre.com/dashboard/api-keys) for higher limits.

## Data Types

### Show Types

Shows are categorized into four types:

* `musical` - Musical theatre productions
* `play` - Dramatic plays
* `comedy` - Comedy productions
* `drama` - Dramatic productions

### Role Types

Cast members have different role types:

* `principal` - Lead performers
* `ensemble` - Ensemble cast
* `understudy` - Understudies
* `swing` - Swing performers
* `standby` - Standbys
* `alternate` - Alternate performers

## Pagination

Currently, all list endpoints return complete datasets. Pagination may be added in future versions for larger datasets.

## CORS

The API supports Cross-Origin Resource Sharing (CORS), allowing you to make requests from browser-based applications.