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

# API Reference

> Complete reference for all Quiz Quail API endpoints

## Base URL

All API requests use the following base URL:

```
https://app.quiz-quail.com/api/v1
```

## Authentication

Every request must include a Bearer token in the `Authorization` header:

```
Authorization: Bearer qk_live_your_api_key_here
```

API keys can be created and managed from your [Dashboard Settings](https://app.quiz-quail.com/settings/api-keys). Keys follow the format `qk_live_...` and can be scoped to specific permissions.

See the [Authentication guide](/authentication) for details on scopes and key management.

## Interactive Playground

You can test endpoints interactively using the [Scalar API Playground](https://app.quiz-quail.com/api/docs) or the built-in playground on each endpoint page below.

## Endpoints

All 43 endpoints grouped by resource:

### Quizzes

| Method   | Path                             | Description      |
| -------- | -------------------------------- | ---------------- |
| `GET`    | `/api/v1/quizzes`                | List quizzes     |
| `POST`   | `/api/v1/quizzes`                | Create a quiz    |
| `GET`    | `/api/v1/quizzes/{id}`           | Get a quiz       |
| `PATCH`  | `/api/v1/quizzes/{id}`           | Update a quiz    |
| `DELETE` | `/api/v1/quizzes/{id}`           | Delete a quiz    |
| `POST`   | `/api/v1/quizzes/{id}/duplicate` | Duplicate a quiz |

### Rounds

| Method   | Path                                    | Description    |
| -------- | --------------------------------------- | -------------- |
| `GET`    | `/api/v1/quizzes/{id}/rounds`           | List rounds    |
| `POST`   | `/api/v1/quizzes/{id}/rounds`           | Create a round |
| `PATCH`  | `/api/v1/quizzes/{id}/rounds/{roundId}` | Update a round |
| `DELETE` | `/api/v1/quizzes/{id}/rounds/{roundId}` | Delete a round |
| `POST`   | `/api/v1/quizzes/{id}/rounds/reorder`   | Reorder rounds |

### Questions

| Method   | Path                                                           | Description       |
| -------- | -------------------------------------------------------------- | ----------------- |
| `GET`    | `/api/v1/quizzes/{id}/rounds/{roundId}/questions`              | List questions    |
| `POST`   | `/api/v1/quizzes/{id}/rounds/{roundId}/questions`              | Create a question |
| `PATCH`  | `/api/v1/quizzes/{id}/rounds/{roundId}/questions/{questionId}` | Update a question |
| `DELETE` | `/api/v1/quizzes/{id}/rounds/{roundId}/questions/{questionId}` | Delete a question |
| `POST`   | `/api/v1/quizzes/{id}/rounds/{roundId}/questions/reorder`      | Reorder questions |

### Themes

| Method   | Path                  | Description    |
| -------- | --------------------- | -------------- |
| `GET`    | `/api/v1/themes`      | List themes    |
| `POST`   | `/api/v1/themes`      | Create a theme |
| `GET`    | `/api/v1/themes/{id}` | Get a theme    |
| `PATCH`  | `/api/v1/themes/{id}` | Update a theme |
| `DELETE` | `/api/v1/themes/{id}` | Delete a theme |

### Media

| Method   | Path                       | Description                                 |
| -------- | -------------------------- | ------------------------------------------- |
| `GET`    | `/api/v1/media`            | List media files                            |
| `POST`   | `/api/v1/media`            | Upload a media file                         |
| `DELETE` | `/api/v1/media/{id}`       | Delete a media file                         |
| `POST`   | `/api/v1/media/signed-url` | Get a signed upload URL                     |
| `GET`    | `/api/v1/media/search`     | Search media (Pexels, Freesound, Wikipedia) |

### Renders

| Method   | Path                            | Description             |
| -------- | ------------------------------- | ----------------------- |
| `GET`    | `/api/v1/renders`               | List renders            |
| `POST`   | `/api/v1/renders`               | Start a render          |
| `GET`    | `/api/v1/renders/{id}`          | Get render status       |
| `DELETE` | `/api/v1/renders/{id}`          | Cancel a render         |
| `GET`    | `/api/v1/renders/{id}/download` | Download rendered video |

### Thumbnails

| Method | Path                 | Description          |
| ------ | -------------------- | -------------------- |
| `POST` | `/api/v1/thumbnails` | Generate a thumbnail |

### YouTube

| Method | Path                                | Description                     |
| ------ | ----------------------------------- | ------------------------------- |
| `GET`  | `/api/v1/youtube/uploads`           | List YouTube uploads            |
| `POST` | `/api/v1/youtube/uploads`           | Start a YouTube upload          |
| `GET`  | `/api/v1/youtube/uploads/{id}`      | Get upload status               |
| `POST` | `/api/v1/youtube/generate-metadata` | Generate video metadata with AI |

### Webhooks

| Method   | Path                         | Description      |
| -------- | ---------------------------- | ---------------- |
| `GET`    | `/api/v1/webhooks`           | List webhooks    |
| `POST`   | `/api/v1/webhooks`           | Create a webhook |
| `DELETE` | `/api/v1/webhooks/{id}`      | Delete a webhook |
| `POST`   | `/api/v1/webhooks/{id}/test` | Test a webhook   |

### AI

| Method | Path                       | Description               |
| ------ | -------------------------- | ------------------------- |
| `POST` | `/api/v1/quizzes/generate` | Generate a quiz with AI   |
| `POST` | `/api/v1/promote`          | Get promotion suggestions |

### Trends

| Method | Path             | Description         |
| ------ | ---------------- | ------------------- |
| `GET`  | `/api/v1/trends` | Get trending topics |