### Install Dependencies with uv

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Installs all project dependencies using `uv`, which also creates the virtual environment.

```sh
uv sync
```

--------------------------------

### Start FastAPI in Production Mode

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Bare-Metal

Use this command to start the FastAPI webserver in production mode. This differs from the development server command.

```bash
fastapi start
```

--------------------------------

### Start FastAPI Development Server

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Starts the FastAPI application in development mode. The website will be accessible at http://localhost:8000.

```sh
just dev # or simply 'just d'
```

```sh
uv run fastapi dev
```

--------------------------------

### Example cURL Request

Source: https://github.com/markbeep/audiobookrequest/wiki/Tutorials/API/API

This cURL command demonstrates how to authenticate and make a request to the /api/users/me endpoint.

```bash
curl -H "Authorization: Bearer <your-api-key-here>" https://abr.example.com/api/users/me
```

--------------------------------

### Query Download Sources and Start Downloads

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Queries Prowlarr for available download sources for a book and initiates downloads. Requires admin privileges for some operations.

```bash
# Get available sources for a book (admin only)
curl -X GET "https://abr.example.com/api/requests/B07RFSSYBH/sources?only_cached=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Refresh sources from Prowlarr
curl -X POST "https://abr.example.com/api/requests/B07RFSSYBH/refresh?force_refresh=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Start download from a specific source (admin only)
curl -X POST "https://abr.example.com/api/requests/B07RFSSYBH/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guid": "source-guid-from-sources-endpoint",
    "indexer_id": 1
  }'

# Trigger auto-download (trusted users)
curl -X POST "https://abr.example.com/api/requests/B07RFSSYBH/auto-download" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Initialize Database with Alembic

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Initializes the database and applies all required migrations using Alembic. This command should be run before starting the application for the first time.

```sh
just alembic_upgrade # or simply 'just au'
```

```sh
uv run alembic upgrade heads
```

--------------------------------

### Get User Recommendations

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve personalized audiobook recommendations based on user history. You can specify limits and offsets for pagination, or use seed ASINs to guide the recommendations.

```bash
# Get personalized recommendations
curl -X GET "https://abr.example.com/api/recommendations/user?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
# Get recommendations with specific seed ASINs
curl -X GET "https://abr.example.com/api/recommendations/user?seed_asins=B07RFSSYBH&seed_asins=B08C6YQLRK&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Download Sources

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Query Prowlarr for available download sources and start downloads.

```APIDOC
## GET /api/requests/{asin}/sources

### Description
Query Prowlarr for available download sources.

### Method
GET

### Endpoint
/api/requests/{asin}/sources

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the book.
#### Query Parameters
- **only_cached** (boolean) - Optional - If true, only return cached sources.

## POST /api/requests/{asin}/refresh

### Description
Refresh download sources from Prowlarr.

### Method
POST

### Endpoint
/api/requests/{asin}/refresh

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the book.
#### Query Parameters
- **force_refresh** (boolean) - Optional - If true, force a refresh even if sources are cached.

## POST /api/requests/{asin}/download

### Description
Start download from a specific source.

### Method
POST

### Endpoint
/api/requests/{asin}/download

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the book.
#### Request Body
- **guid** (string) - Required - The GUID of the source to download from.
- **indexer_id** (integer) - Required - The ID of the indexer.

## POST /api/requests/{asin}/auto-download

### Description
Trigger auto-download for a book (trusted users).

### Method
POST

### Endpoint
/api/requests/{asin}/auto-download

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the book.
```

--------------------------------

### Run Application with Docker Compose

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Builds and starts the application locally using Docker Compose with the 'local' profile enabled.

```bash
docker compose --profile local up --build
```

--------------------------------

### Get Indexer Configurations

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieves all available indexer configuration options. Requires authentication.

```bash
# Get indexer configurations
curl -X GET "https://abr.example.com/api/indexers/configurations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Gotify Notification Setup

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Configure Gotify push notifications by specifying the URL, headers (including the app token), and the JSON body with placeholders for dynamic content.

```bash
# Gotify notification setup
# URL: https://gotify.example.com/message
# Headers: {"X-Gotify-Key": "your_app_token"}
# Body Type: JSON
# Body:
{
  "title": "New Request: {bookTitle}",
  "message": "{bookTitle} by {bookAuthors} requested by {eventUser}"
}
```

--------------------------------

### Run Audiobook Request Docker Container

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Docker

Use this command to start the application container. It maps port 8000 and mounts a local config directory. Ensure you are in the directory where you want the config to be created.

```bash
docker run -p 8000:8000 -v $(pwd)/config:/config markbeep/audiobookrequest:1
```

--------------------------------

### OIDC Configuration Example

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

This YAML snippet shows the required OpenID Connect (OIDC) settings that need to be configured in the application's security settings for external authentication.

```yaml
# Required OIDC settings (configure in Settings > Security)

```

--------------------------------

### Example Indexer Configuration JSON

Source: https://github.com/markbeep/audiobookrequest/wiki/Tutorials/Indexer-From-File

This JSON file structure is used to update indexer configurations. Ensure the file is accessible by ABR and provides an absolute path in the settings.

```json
{
  "MyAnonamouse": {
    "mam_session_id": "test3"
  }
}
```

--------------------------------

### Get Indexer Configurations

Source: https://github.com/markbeep/audiobookrequest/wiki/Tutorials/API/Indexers

Retrieves the current configuration settings for all available indexers. This helps in understanding which parameters can be adjusted.

```APIDOC
## GET /api/indexers/configurations

### Description
Retrieves the current configuration settings for all available indexers.

### Method
GET

### Endpoint
/api/indexers/configurations

### Response
#### Success Response (200)
- **indexer_name** (object) - An object where keys are indexer names and values are arrays of their configuration parameters.
  - **name** (str) - The name of the configuration parameter.
  - **description** (str) - A description of the parameter.
  - **default** (any) - The default value for the parameter.
  - **required** (bool) - Whether the parameter is required.
  - **type** (str) - The data type of the parameter.

#### Response Example
```json
{
  "MyAnonamouse": [
    {
      "name": "mam_session_id",
      "description": null,
      "default": null,
      "required": true,
      "type": "str"
    }
  ]
}
```
```

--------------------------------

### Start Tailwind CSS Watcher

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Starts the Tailwind CSS watcher to automatically recompile CSS when source files change. This is required for any CSS styling to be applied.

```sh
just tailwind # or simply 'just tw'
```

```sh
tailwindcss -i static/tw.css -o static/globals.css --watch
```

```sh
npx @tailwindcss/cli@4 -i static/tw.css -o static/globals.css --watch
```

--------------------------------

### Get Search Suggestions

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve autocomplete suggestions for audiobook search queries. Requires a query parameter 'q' and an optional 'region'.

```bash
# Get search suggestions
curl -X GET "https://abr.example.com/api/search/suggestions?q=stephen+king&region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response returns list of suggested search terms
["stephen king", "stephen king it", "stephen king the shining", "stephen king pet sematary"]
```

--------------------------------

### Get Current User Information

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieves detailed information about the currently authenticated user. Requires a valid API key.

```bash
# Get current user info
curl -X GET "https://abr.example.com/api/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "username": "johndoe",
  "group": "trusted",
  "root": false
}
```

--------------------------------

### Get Category Recommendations

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Browse audiobook recommendations filtered by Audible categories. Requires specifying the Audible region.

```bash
# Get recommendations by category
curl -X GET "https://abr.example.com/api/recommendations/categories?audible_region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get Search Suggestions

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve autocomplete suggestions for search queries.

```APIDOC
## Get Search Suggestions

Retrieve autocomplete suggestions for search queries.

### Method
GET

### Endpoint
/api/search/suggestions

### Query Parameters
- **q** (string) - Required - The search query for suggestions.
- **region** (string) - Optional - The region for suggestions (e.g., 'us'). Defaults to 'us'.

### Request Example
```bash
curl -X GET "https://abr.example.com/api/search/suggestions?q=stephen+king&region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **suggestions** (array of strings) - A list of suggested search terms.

#### Response Example
```json
["stephen king", "stephen king it", "stephen king the shining", "stephen king pet sematary"]
```
```

--------------------------------

### Get Author/Narrator Recommendations

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve audiobook recommendations based on your favorite authors or narrators from your user history. You can specify the Audible region for author recommendations.

```bash
# Get recommendations based on favorite authors
curl -X GET "https://abr.example.com/api/recommendations/authors?limit=10&personal_favorites=true&audible_region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
# Get recommendations based on favorite narrators
curl -X GET "https://abr.example.com/api/recommendations/narrators?limit=10&personal_favorites=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Deploy AudioBookRequest with Docker Compose

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Docker Compose configuration for deploying AudioBookRequest, including optional PostgreSQL setup. Environment variables control application settings and database connection.

```yaml
services:
  audiobookrequest:
    image: markbeep/audiobookrequest:1
    ports:
      - '8000:8000'
    volumes:
      - ./config:/config
    environment:
      ABR_APP__PORT: 8000
      ABR_APP__OPENAPI_ENABLED: true
      ABR_APP__DEFAULT_REGION: us
      ABR_APP__LOG_LEVEL: INFO
      # PostgreSQL configuration (optional)
      ABR_DB__USE_POSTGRES: false
      ABR_DB__POSTGRES_HOST: localhost
      ABR_DB__POSTGRES_PORT: 5432
      ABR_DB__POSTGRES_DB: audiobookrequest
      ABR_DB__POSTGRES_USER: abr
      ABR_DB__POSTGRES_PASSWORD: password

  # Optional PostgreSQL database
  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: abr
      POSTGRES_PASSWORD: password
      POSTGRES_DB: audiobookrequest
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    ports:
      - "5432:5432"
```

--------------------------------

### Get Recent Requests

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve audiobooks that have been recently requested. You can specify the number of days back to consider and exclude already downloaded books.

```bash
# Get books requested in the last 30 days
curl -X GET "https://abr.example.com/api/recommendations/recent?limit=10&days_back=30&exclude_downloaded=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get Indexer Configurations

Source: https://github.com/markbeep/audiobookrequest/wiki/Tutorials/API/Indexers

Retrieve the available configuration settings for indexers to understand adjustable parameters. This response provides details on each configurable field, including its name, description, default value, whether it's required, and its data type.

```json
{
  "MyAnonamouse": [
    {
      "name": "mam_session_id",
      "description": null,
      "default": null,
      "required": true,
      "type": "str"
    }
  ]
}
```

--------------------------------

### Discord Webhook Notification Example

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Configure Discord webhook notifications using a JSON payload with embeds for rich formatting. Placeholders are used for dynamic content.

```json
// Discord notification body (JSON type)
{
  "content": "New audiobook request from {eventUser}!",
  "embeds": [
    {
      "title": "{bookTitle}",
      "description": "By {bookAuthors}",
      "thumbnail": {"url": "{bookCover}"},
      "fields": [
        {"name": "Narrated by", "value": "{bookNarrators}", "inline": true},
        {"name": "ASIN", "value": "{bookASIN}", "inline": true}
      ]
    }
  ]
}
```

--------------------------------

### Get Popular Books

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve a list of the most requested audiobooks. You can filter by a minimum request threshold, set a limit for the number of results, and exclude books the user has already downloaded.

```bash
# Get popular books with minimum request threshold
curl -X GET "https://abr.example.com/api/recommendations/popular?min_requests=2&limit=10&exclude_downloaded=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Authenticate API Requests with Bearer Token

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

All API endpoints require Bearer token authentication. Include the 'Authorization' header with your generated API key. The example shows fetching the current user's details.

```bash
# API requests require the Authorization header
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  https://abr.example.com/api/users/me

# Example response
{
  "username": "admin",
  "group": "admin",
  "root": true
}
```

--------------------------------

### Configure PostgreSQL Database

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Enable and configure PostgreSQL as the database backend. This includes settings for host, port, database name, user, password, and SSL mode.

```bash
ABR_DB__USE_POSTGRES=false
ABR_DB__POSTGRES_HOST=localhost
ABR_DB__POSTGRES_PORT=5432
ABR_DB__POSTGRES_DB=audiobookrequest
ABR_DB__POSTGRES_USER=abr
ABR_DB__POSTGRES_PASSWORD=password
ABR_DB__POSTGRES_SSL_MODE=prefer
```

--------------------------------

### Configure Application Settings

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Set application-level configurations such as server port, debug mode, OpenAPI enablement, configuration directory, log level, base URL, default region, and censorship.

```bash
ABR_APP__PORT=8000
ABR_APP__DEBUG=false
ABR_APP__OPENAPI_ENABLED=false
ABR_APP__CONFIG_DIR=/config
ABR_APP__LOG_LEVEL=INFO
ABR_APP__BASE_URL=
ABR_APP__DEFAULT_REGION=us
ABR_APP__DISABLE_CENSOR=false
```

--------------------------------

### Configure Authentication Settings

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Define authentication behavior by forcing a login type or setting an initial root username and password.

```bash
ABR_APP__FORCE_LOGIN_TYPE=
ABR_APP__INIT_ROOT_USERNAME=
ABR_APP__INIT_ROOT_PASSWORD=
```

--------------------------------

### Configure SQLite Database

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Specify the path for the SQLite database file. This is the default database configuration.

```bash
ABR_DB__SQLITE_PATH=db.sqlite
```

--------------------------------

### Fetch JavaScript Files

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Bare-Metal

Run this script to download necessary JavaScript files for the static directory. Ensure you are in the correct project directory.

```bash
uv run python /app/util/fetch_js.py
```

--------------------------------

### Create an Audiobook Request

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Request an audiobook by its ASIN. This action triggers notifications and auto-download for trusted users. The response includes book details and the current request list.

```bash
# Create a new audiobook request
curl -X POST "https://abr.example.com/api/requests/B07RFSSYBH?region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response includes book details and request list
{
  "book": {
    "asin": "B07RFSSYBH",
    "title": "Atomic Habits",
    "authors": ["James Clear"],
    "downloaded": false
  },
  "requests": [
    {
      "asin": "B07RFSSYBH",
      "user_username": "johndoe",
      "updated_at": "2024-01-15T10:30:00"
    }
  ],
  "username": "johndoe"
}
```

--------------------------------

### Download DaisyUI Assets

Source: https://github.com/markbeep/audiobookrequest/wiki/Local-Development

Downloads the necessary DaisyUI JavaScript files for styling. These files are saved in the `static/` directory.

```sh
just install_daisy
```

```sh
curl -sLo static/daisyui.mjs https://github.com/saadeghi/daisyui/releases/latest/download/daisyui.mjs
```

```sh
curl -sLo static/daisyui-theme.mjs https://github.com/saadeghi/daisyui/releases/latest/download/daisyui-theme.mjs
```

--------------------------------

### List Manual Book Requests

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieves a list of all manually created book requests. Requires authentication.

```bash
# List all manual requests
curl -X GET "https://abr.example.com/api/requests/manual" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_username": "johndoe",
    "title": "Custom Audiobook Title",
    "authors": ["Author Name"],
    "narrators": ["Narrator Name"],
    "downloaded": false
  }
]
```

--------------------------------

### Create New User Account

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Creates a new user account with specified credentials and group. This operation is limited to administrators.

```bash
# Create new user
curl -X POST "https://abr.example.com/api/users/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "securepassword123",
    "group": "untrusted",
    "root": false,
    "extra_data": "discord_id:123456789"
  }'

# Response (201 Created)
{
  "username": "newuser",
  "group": "untrusted",
  "root": false
}
```

--------------------------------

### Configure Indexer Settings with JSON File

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Configure indexers by placing a JSON file in a mounted volume for automated updates. This method is useful for managing settings declaratively.

```json
// /config/indexers.json - Place in mounted volume
{
  "MyAnonamouse": {
    "mam_session_id": "session_cookie_value_here",
    "enabled": true
  }
}
```

--------------------------------

### Create Manual Book Request

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Creates a request for audiobooks that are not available on Audible. Requires book details such as title, author, and narrator.

```bash
# Create manual book request
curl -X POST "https://abr.example.com/api/requests/manual" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Custom Audiobook Title",
    "author": "Author Name",
    "narrator": "Narrator Name",
    "subtitle": "Optional Subtitle",
    "publish_date": "2024",
    "info": "Additional information about the book"
  }'

# Returns 201 Created on success
```

--------------------------------

### Mark Book as Downloaded

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Marks a book as downloaded. This action is restricted to administrators and triggers download success notifications.

```bash
# Mark book as downloaded
curl -X PATCH "https://abr.example.com/api/requests/B07RFSSYBH/downloaded" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Returns 204 No Content on success
```

--------------------------------

### Create a Book Request

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Request an audiobook by its ASIN. This action triggers notifications and auto-download for trusted users.

```APIDOC
## Create a Book Request

Request an audiobook by its ASIN. Triggers notifications and auto-download for trusted users.

### Method
POST

### Endpoint
/api/requests/{asin}

### Path Parameters
- **asin** (string) - Required - The ASIN of the audiobook to request.

### Query Parameters
- **region** (string) - Optional - The region for the request (e.g., 'us'). Defaults to 'us'.

### Request Example
```bash
curl -X POST "https://abr.example.com/api/requests/B07RFSSYBH?region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **book** (object) - Details of the requested audiobook.
  - **asin** (string) - The ASIN of the book.
  - **title** (string) - The title of the book.
  - **authors** (array of strings) - The authors of the book.
  - **downloaded** (boolean) - Indicates if the book has been downloaded.
- **requests** (array of objects) - List of users who have requested this book.
  - **asin** (string) - The ASIN of the book.
  - **user_username** (string) - The username of the user who made the request.
  - **updated_at** (string) - The timestamp when the request was last updated.
- **username** (string) - The username of the user making the current request.

#### Response Example
```json
{
  "book": {
    "asin": "B07RFSSYBH",
    "title": "Atomic Habits",
    "authors": ["James Clear"],
    "downloaded": false
  },
  "requests": [
    {
      "asin": "B07RFSSYBH",
      "user_username": "johndoe",
      "updated_at": "2024-01-15T10:30:00"
    }
  ],
  "username": "johndoe"
}
```
```

--------------------------------

### Basic Docker Compose Configuration

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Docker-Compose

This is the fundamental Docker Compose file for the audiobookrequest application. It defines the web service, specifies the Docker image to use, maps ports, and mounts a local configuration volume.

```yaml
services:
  web:
    image: markbeep/audiobookrequest:1
    ports:
      - '8000:8000'
    volumes:
      - ./config:/config
```

--------------------------------

### List All Users

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieves a paginated list of all users in the system. This endpoint is restricted to administrators.

```bash
# List users with pagination
curl -X GET "https://abr.example.com/api/users/?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "users": [
    {"username": "admin", "group": "admin", "root": true},
    {"username": "johndoe", "group": "trusted", "root": false}
  ],
  "total": 2
}
```

--------------------------------

### Create Manual Request

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Create a request for books not available on Audible.

```APIDOC
## POST /api/requests/manual

### Description
Create a request for books not available on Audible.

### Method
POST

### Endpoint
/api/requests/manual

### Parameters
#### Request Body
- **title** (string) - Required - The title of the audiobook.
- **author** (string) - Required - The author of the audiobook.
- **narrator** (string) - Optional - The narrator of the audiobook.
- **subtitle** (string) - Optional - The subtitle of the audiobook.
- **publish_date** (string) - Optional - The publication date of the audiobook.
- **info** (string) - Optional - Additional information about the book.

### Request Example
```json
{
  "title": "Custom Audiobook Title",
  "author": "Author Name",
  "narrator": "Narrator Name",
  "subtitle": "Optional Subtitle",
  "publish_date": "2024",
  "info": "Additional information about the book"
}
```

### Response
#### Success Response (201)
Returns the created request details.
```

--------------------------------

### List Manual Requests

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve all manual book requests.

```APIDOC
## GET /api/requests/manual

### Description
Retrieve all manual book requests.

### Method
GET

### Endpoint
/api/requests/manual

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the request.
- **user_username** (string) - The username of the user who made the request.
- **title** (string) - The title of the audiobook.
- **authors** (array of strings) - The authors of the audiobook.
- **narrators** (array of strings) - The narrators of the audiobook.
- **downloaded** (boolean) - Indicates if the audiobook has been downloaded.

#### Response Example
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_username": "johndoe",
    "title": "Custom Audiobook Title",
    "authors": ["Author Name"],
    "narrators": ["Narrator Name"],
    "downloaded": false
  }
]
```
```

--------------------------------

### Run FastAPI with Custom Port

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Bare-Metal

If you need to specify a custom port for the FastAPI application, use the --port flag. The default port can be configured via the ABR_APP__PORT environment variable.

```bash
fastapi run --port 5432
```

--------------------------------

### Kubernetes Deployment Configuration

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Kubernetes

Use this YAML configuration to deploy the audiobookrequest application on Kubernetes. It specifies the container image, replica count, and volume mounts for configuration files. The volume can be a host path or a Persistent Volume Claim.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: audiobookrequest
  labels:
    app: audiobookrequest
spec:
  replicas: 1
  selector:
    matchLabels:
      app: audiobookrequest
  template:
    metadata:
      labels:
        app: audiobookrequest
    spec:
      containers:
        - name: audiobookrequest
          image: markbeep/audiobookrequest:1
          imagePullPolicy: Always
          volumeMounts:
            - mountPath: /config
              name: abr-config
          ports:
            - name: http-request
              containerPort: 8000
      volumes:
        - name: abr-config
          hostPath:
            path: /mnt/disk/AudioBookRequest/
```

--------------------------------

### List All Audiobook Requests

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve all audiobook requests. Admins see all requests, while regular users see only their own. Supports filtering by download status.

```bash
# List all requests (admin sees all, users see their own)
curl -X GET "https://abr.example.com/api/requests?filter=not_downloaded" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter options: all, downloaded, not_downloaded
```

--------------------------------

### Mark as Downloaded

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Mark a book as downloaded (admin only). Triggers download success notifications.

```APIDOC
## PATCH /api/requests/{asin}/downloaded

### Description
Mark a book as downloaded (admin only). Triggers download success notifications.

### Method
PATCH

### Endpoint
/api/requests/{asin}/downloaded

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the book to mark as downloaded.

### Request Example
```bash
curl -X PATCH "https://abr.example.com/api/requests/B07RFSSYBH/downloaded" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (204)
No Content on success.
```

--------------------------------

### OpenID Connect Authentication

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Configure external authentication providers using OpenID Connect.

```APIDOC
## OIDC Configuration

### Description
Configure external authentication providers like Authentik or Keycloak using OpenID Connect.

### Required Settings
These settings need to be configured in the application's `Settings > Security` section.

```yaml
# Required OIDC settings (configure in Settings > Security)
```
```

--------------------------------

### List All Requests

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Retrieve all book requests. Admins see all requests, while regular users see only their own. Supports filtering by download status.

```APIDOC
## List All Requests

Retrieve all book requests with optional filtering by download status.

### Method
GET

### Endpoint
/api/requests

### Query Parameters
- **filter** (string) - Optional - Filters the requests. Options: 'all', 'downloaded', 'not_downloaded'. Defaults to 'all'.

### Request Example
```bash
# List all requests (admin sees all, users see their own)
curl -X GET "https://abr.example.com/api/requests?filter=not_downloaded" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- Returns a list of audiobook requests based on the filter applied. The structure of each request object is similar to the response of the 'Create a Book Request' endpoint.
```

--------------------------------

### Update Indexer Configuration via API

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Use this endpoint to update configuration values for a specific indexer. The indexer name is case-sensitive. A successful update returns a 204 No Content status.

```bash
# Update indexer configuration (case-sensitive name)
curl -X PATCH "https://abr.example.com/api/indexers/MyAnonamouse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mam_session_id": "your_mam_session_cookie_value",
    "enabled": true
  }'

# Returns 204 No Content on success
```

--------------------------------

### Notifications Configuration

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Configure webhook notifications for various events.

```APIDOC
## Notification Body Templates

### Description
Templates for notification payloads, with placeholders for event-specific data.

### Available Placeholders (Common)
- **eventType**: Type of the event.
- **eventUser**: User associated with the event.
- **eventUserExtraData**: Additional data about the user.
- **joinedUsers**: List of users joined.
- **bookTitle**: Title of the book.
- **bookAuthors**: Authors of the book.
- **bookNarrators**: Narrators of the book.
- **bookASIN**: ASIN of the book.
- **bookCover**: URL of the book cover.

### Placeholders for Download Events
- **sourceTitle**: Title of the source.
- **sourceSizeMB**: Size of the source in MB.
- **indexerName**: Name of the indexer.
- **torrentInfoHash**: Info hash of the torrent.
- **sourceProtocol**: Protocol of the source.

### Placeholders for Failed Downloads
- **errorStatus**: Status code of the error.
- **errorReason**: Reason for the error.
```

```APIDOC
## Discord Webhook Configuration

### Description
Configure Discord webhook notifications with embeds for rich formatting.

### Request Body Example (JSON)
```json
{
  "content": "New audiobook request from {eventUser}!",
  "embeds": [
    {
      "title": "{bookTitle}",
      "description": "By {bookAuthors}",
      "thumbnail": {"url": "{bookCover}"},
      "fields": [
        {"name": "Narrated by", "value": "{bookNarrators}", "inline": true},
        {"name": "ASIN", "value": "{bookASIN}", "inline": true}
      ]
    }
  ]
}
```
```

```APIDOC
## Gotify Notification Configuration

### Description
Configure Gotify push notifications.

### Setup Details
- **URL**: `https://gotify.example.com/message`
- **Headers**: `{"X-Gotify-Key": "your_app_token"}`
- **Body Type**: `JSON`

### Request Body Example
```json
{
  "title": "New Request: {bookTitle}",
  "message": "{bookTitle} by {bookAuthors} requested by {eventUser}"
}
```
```

--------------------------------

### Docker Compose with Environment Variables

Source: https://github.com/markbeep/audiobookrequest/wiki/Getting-Started/Running the App/Docker-Compose

An extended Docker Compose configuration that includes environment variables. This allows for customization of application behavior, such as setting the application port or enabling/disabling OpenAPI documentation.

```yaml
services:
  web:
    image: markbeep/audiobookrequest:1
    ports:
      - '8000:5432'
    volumes:
      - ./config:/config
    environment:
      ABR_APP__PORT: 5432
      ABR_APP__OPENAPI_ENABLED: true
```

--------------------------------

### Recommendations API

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Endpoints for retrieving various types of audiobook recommendations.

```APIDOC
## GET /api/recommendations/user

### Description
Get personalized audiobook recommendations based on user history.

### Method
GET

### Endpoint
/api/recommendations/user

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of recommendations to return.
- **offset** (integer) - Optional - The number of recommendations to skip.
- **seed_asins** (string) - Optional - ASINs to seed the recommendations. Can be specified multiple times.

### Request Example
```bash
# Get personalized recommendations
curl -X GET "https://abr.example.com/api/recommendations/user?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get recommendations with specific seed ASINs
curl -X GET "https://abr.example.com/api/recommendations/user?seed_asins=B07RFSSYBH&seed_asins=B08C6YQLRK&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

```APIDOC
## GET /api/recommendations/popular

### Description
Retrieve the most requested audiobooks.

### Method
GET

### Endpoint
/api/recommendations/popular

### Parameters
#### Query Parameters
- **min_requests** (integer) - Optional - Minimum number of requests for a book to be included.
- **limit** (integer) - Optional - The maximum number of popular books to return.
- **exclude_downloaded** (boolean) - Optional - Whether to exclude books already downloaded by the user.

### Request Example
```bash
# Get popular books with minimum request threshold
curl -X GET "https://abr.example.com/api/recommendations/popular?min_requests=2&limit=10&exclude_downloaded=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **book** (object) - Information about the book.
  - **asin** (string) - The ASIN of the book.
  - **title** (string) - The title of the book.
- **request_count** (integer) - The number of times the book has been requested.
```

```APIDOC
## GET /api/recommendations/recent

### Description
Retrieve recently requested audiobooks.

### Method
GET

### Endpoint
/api/recommendations/recent

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of recent requests to return.
- **days_back** (integer) - Optional - The number of past days to consider for recent requests.
- **exclude_downloaded** (boolean) - Optional - Whether to exclude books already downloaded by the user.

### Request Example
```bash
# Get books requested in the last 30 days
curl -X GET "https://abr.example.com/api/recommendations/recent?limit=10&days_back=30&exclude_downloaded=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

```APIDOC
## GET /api/recommendations/categories

### Description
Browse recommendations by Audible categories.

### Method
GET

### Endpoint
/api/recommendations/categories

### Parameters
#### Query Parameters
- **audible_region** (string) - Required - The Audible region to fetch categories from (e.g., 'us').

### Request Example
```bash
# Get recommendations by category
curl -X GET "https://abr.example.com/api/recommendations/categories?audible_region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **(object)** - An object where keys are category names and values are arrays of recommended books within that category.
```

```APIDOC
## GET /api/recommendations/authors

### Description
Get recommendations based on popular authors from user history.

### Method
GET

### Endpoint
/api/recommendations/authors

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of recommendations to return.
- **personal_favorites** (boolean) - Optional - If true, prioritize authors marked as personal favorites.
- **audible_region** (string) - Optional - The Audible region to consider.

### Request Example
```bash
# Get recommendations based on favorite authors
curl -X GET "https://abr.example.com/api/recommendations/authors?limit=10&personal_favorites=true&audible_region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

```APIDOC
## GET /api/recommendations/narrators

### Description
Get recommendations based on popular narrators from user history.

### Method
GET

### Endpoint
/api/recommendations/narrators

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of recommendations to return.
- **personal_favorites** (boolean) - Optional - If true, prioritize narrators marked as personal favorites.

### Request Example
```bash
# Get recommendations based on favorite narrators
curl -X GET "https://abr.example.com/api/recommendations/narrators?limit=10&personal_favorites=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

--------------------------------

### Users API

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Endpoints for managing user accounts.

```APIDOC
## GET /api/users/

### Description
Retrieve paginated list of all users (admin only).

### Method
GET

### Endpoint
/api/users/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of users to return.
- **offset** (integer) - Optional - The number of users to skip.

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
  - **username** (string) - The username.
  - **group** (string) - The user's group.
  - **root** (boolean) - Whether the user is a root user.
- **total** (integer) - The total number of users.

#### Response Example
```json
{
  "users": [
    {"username": "admin", "group": "admin", "root": true},
    {"username": "johndoe", "group": "trusted", "root": false}
  ],
  "total": 2
}
```

## GET /api/users/me

### Description
Retrieve information about the authenticated user.

### Method
GET

### Endpoint
/api/users/me

### Response
#### Success Response (200)
- **username** (string) - The username.
- **group** (string) - The user's group.
- **root** (boolean) - Whether the user is a root user.

#### Response Example
```json
{
  "username": "johndoe",
  "group": "trusted",
  "root": false
}
```

## POST /api/users/

### Description
Create a new user account (admin only).

### Method
POST

### Endpoint
/api/users/

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new account.
- **password** (string) - Required - The password for the new account.
- **group** (string) - Optional - The group for the new user (default: "untrusted").
- **root** (boolean) - Optional - Whether the user should have root privileges (default: false).
- **extra_data** (string) - Optional - Additional data for the user (e.g., "discord_id:123456789").

### Response
#### Success Response (201)
- **username** (string) - The username.
- **group** (string) - The user's group.
- **root** (boolean) - Whether the user is a root user.

#### Response Example
```json
{
  "username": "newuser",
  "group": "untrusted",
  "root": false
}
```

## PUT /api/users/{username}

### Description
Update user password, group, or extra data (admin only).

### Method
PUT

### Endpoint
/api/users/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to update.
#### Request Body
- **password** (string) - Optional - The new password for the user.
- **group** (string) - Optional - The new group for the user.
- **extra_data** (string) - Optional - Additional data for the user.

### Response
#### Success Response (200)
- **username** (string) - The username.
- **group** (string) - The user's group.
- **root** (boolean) - Whether the user is a root user.

#### Response Example
```json
{
  "username": "johndoe",
  "group": "trusted",
  "root": false
}
```

## DELETE /api/users/{username}

### Description
Permanently remove a user (admin only, cannot delete self or root).

### Method
DELETE

### Endpoint
/api/users/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to delete.

### Response
#### Success Response (204)
No Content on success.
```

--------------------------------

### Search Audiobooks via Audible API

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Search for audiobooks using the Audible API. Parameters include query, number of results, page number, and region. The response includes audiobook details and request status.

```bash
# Search for audiobooks by query
curl -X GET "https://abr.example.com/api/search?q=atomic+habits&num_results=10&page=0&region=us" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response contains audiobook details with request status
[
  {
    "book": {
      "asin": "B07RFSSYBH",
      "title": "Atomic Habits",
      "subtitle": "An Easy & Proven Way to Build Good Habits & Break Bad Ones",
      "authors": ["James Clear"],
      "narrators": ["James Clear"],
      "cover_image": "https://m.media-amazon.com/images/",
      "release_date": "2018-10-16T00:00:00",
      "runtime_length_min": 319,
      "downloaded": false
    },
    "requests": [],
    "username": "admin"
  }
]
```

--------------------------------

### Indexers API

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Endpoints for managing indexer configurations.

```APIDOC
## GET /api/indexers/configurations

### Description
Retrieve all available indexer configuration options.

### Method
GET

### Endpoint
/api/indexers/configurations

### Response
#### Success Response (200)
Returns a list of available indexer configurations.
```

--------------------------------

### Authelia OIDC Configuration

Source: https://github.com/markbeep/audiobookrequest/wiki/Tutorials/OIDC/OpenID-Connect-With-Authelia

This YAML configuration defines the OIDC client settings for Authelia. Ensure `redirect_uris` ends with `/auth/oidc` and `token_endpoint_auth_method` is set to `client_secret_post`.

```yaml
client_id: 'clientID' 
client_name: 'AudioBookRequest'
client_secret: '[secret]'
public: false
authorization_policy: 'one_factor'
require_pkce: 'false'
redirect_uris:
  - 'https://abr.example.com/auth/oidc'
scopes:
  - 'openid'
  - 'profile'
  - 'groups'
  - 'email'
response_types:
  - 'code'
grant_types:
  - 'authorization_code'
access_token_signed_response_alg: 'none'
userinfo_signed_response_alg: 'none'
token_endpoint_auth_method: 'client_secret_post'
```

--------------------------------

### Update Indexer Settings

Source: https://context7.com/markbeep/audiobookrequest/llms.txt

Update configuration values for a specific indexer using its name. This can be done via API call or by providing a JSON configuration file.

```APIDOC
## PATCH /api/indexers/{indexer_name}

### Description
Update configuration values for a specific indexer.

### Method
PATCH

### Endpoint
/api/indexers/{indexer_name}

### Parameters
#### Path Parameters
- **indexer_name** (string) - Required - The case-sensitive name of the indexer to update.

#### Request Body
- **mam_session_id** (string) - Optional - The session ID for the indexer.
- **enabled** (boolean) - Optional - Whether the indexer is enabled.

### Request Example
```json
{
  "mam_session_id": "your_mam_session_cookie_value",
  "enabled": true
}
```

### Response
#### Success Response (204)
No Content on success.
```

```APIDOC
## File-Based Indexer Configuration

### Description
Configure indexers using a JSON file for automated updates. Place the `indexers.json` file in a mounted volume.

### File Structure
```json
{
  "MyAnonamouse": {
    "mam_session_id": "session_cookie_value_here",
    "enabled": true
  }
}
```
```