### Build and Start Playwright Reports Server

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Build the project and start the Playwright Reports Server. The server will be accessible at http://localhost:3000.

```bash
npm run build && npm run start
```

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

### Get Configuration

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns server configuration including UI customization and environment settings.

```APIDOC
## GET /api/config

### Description
Returns server configuration including UI customization and environment settings.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **title** (string) - The title of the application.
- **logoPath** (string) - The path to the logo.
- **faviconPath** (string) - The path to the favicon.
- **headerLinks** (object) - Links to display in the header.
  - **github** (string) - URL for the GitHub link.
- **authRequired** (boolean) - Whether authentication is required.
- **serverCache** (boolean) - Whether server-side caching is enabled.
- **dataStorage** (string) - The type of data storage used.

#### Response Example
```json
{
  "title": "My Test Reports",
  "logoPath": "/logo.svg",
  "faviconPath": "/favicon.ico",
  "headerLinks": {
    "github": "https://github.com/myorg/myrepo"
  },
  "authRequired": true,
  "serverCache": false,
  "dataStorage": "fs"
}
```
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Clone the Playwright Reports Server repository and install project dependencies using npm.

```bash
git clone https://github.com/CyborgTests/playwright-reports-server.git
cd playwright-reports-server
npm install
```

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

### Report List Response Example

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example JSON response from the `/api/report/list` endpoint, showing details of generated reports including report ID, creation date, project name, size, and URL.

```json
{
  "reports": [
    {
      "reportID": "8e9af87d-1d10-4729-aefd-3e92ee64d06c",
      "createdAt": "2024-05-06T16:52:45.017Z",
      "project": "regression",
      "size": "6.97 MB",
      "reportUrl": "/api/serve/regression/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html"
      //...parsed info
    },
    {
      "reportID": "8fe427ed-783c-4fb9-aacc-ba6fbc5f5667",
      "createdAt": "2024-05-06T16:59:38.814Z",
      "project": "smoke",
      "size": "1.53 MB",
      "reportUrl": "/api/serve/smoke/8fe427ed-783c-4fb9-aacc-ba6fbc5f5667/index.html"
      //...parsed info
    }
  ],
  "total": 2
}
```

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

### Get Server Info - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response containing server statistics such as data folder size, number of results, and reports.

```json
{
  "dataFolderSizeinMB": "0.00 MB",
  "numOfResults": 0,
  "resultsFolderSizeinMB": "0.00 MB",
  "numOfReports": 0,
  "reportsFolderSizeinMB": "0.00 MB"
}
```

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

### Get Server Configuration

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns server configuration including UI customization and environment settings.

```bash
curl --location 'http://localhost:3000/api/config' \
  --header 'Authorization: my-api-token'
```

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

### Example UI Configuration JSON

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

This JSON file can be placed in the `/data/` folder to configure the UI. Ensure the `/data/` folder is persisted if running in Docker to maintain changes.

```json
{
  "title": "Custom title",
  "headerLinks": {
    "someLink": "https://example.com",
    "github": "https://github.com/YourName"
  },
  "logoPath": "/logo.svg",
  "faviconPath": "/favicon.ico"
}
```

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

### Get Server Info

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns storage statistics including total data size, number of reports and results.

```bash
curl --location 'http://localhost:3000/api/info' \
  --header 'Authorization: my-api-token'
```

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

### List Existing Results - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response containing an array of available results, including their IDs, creation dates, sizes, projects, and test run names.

```json
{
  "results": [
    {
      "resultID": "a7beb04b-f190-4fbb-bebd-58b2c776e6c3",
      "createdAt": "2024-05-06T16:40:33.021Z",
      "size": "1.93 MB",
      "project": "regression",
      "testRunName": "regression-run-v1.10",
      "reporter": "okhotemskyi"
    }
  ],
  "total": 1
}
```

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

### GET /api/info

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Retrieves server statistics and resource usage information.

```APIDOC
## GET /api/info

### Description
Returns server statistics, including disk usage for data and reports, and counts of results and reports.

### Method
GET

### Endpoint
/api/info

### Response
#### Success Response (200)
- **dataFolderSizeinMB** (string) - Size of the data folder in MB.
- **numOfResults** (integer) - Number of stored results.
- **resultsFolderSizeinMB** (string) - Size of the results folder in MB.
- **numOfReports** (integer) - Number of stored reports.
- **reportsFolderSizeinMB** (string) - Size of the reports folder in MB.

#### Response Example
```json
{
  "dataFolderSizeinMB": "0.00 MB",
  "numOfResults": 0,
  "resultsFolderSizeinMB": "0.00 MB",
  "numOfReports": 0,
  "reportsFolderSizeinMB": "0.00 MB"
}
```
```

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

### Docker Run with Mounted Volume

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example Docker command to run the Playwright Reports Server with a local volume mounted for persistent data storage.

```sh
docker run -v /path/on/host:/app/data -p 3000:3000 playwright-reports-server
```

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

### Generate Report - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response upon successful report generation, including the report ID and URL.

```json
{
  "project": "regression",
  "reportId": "8e9af87d-1d10-4729-aefd-3e92ee64d06c",
  "reportUrl": "/api/serve/regression/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html"
}
```

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

### GET /api/result/list

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Retrieves a list of all available results (raw zip archives) on the server.

```APIDOC
## GET /api/result/list

### Description
Returns a list of all currently existing results (raw zip archives) stored on the server.

### Method
GET

### Endpoint
/api/result/list

### Response
#### Success Response (200)
- **results** (array) - An array of result objects.
  - **resultID** (string) - The unique identifier for the result.
  - **createdAt** (string) - The timestamp when the result was created.
  - **size** (string) - The size of the result archive.
  - **project** (string) - The project associated with the result.
  - **testRunName** (string) - The name of the test run.
  - **reporter** (string) - The reporter used for this result.
- **total** (integer) - The total number of results available.

#### Response Example
```json
{
  "results": [
    {
      "resultID": "a7beb04b-f190-4fbb-bebd-58b2c776e6c3",
      "createdAt": "2024-05-06T16:40:33.021Z",
      "size": "1.93 MB",
      "project": "regression",
      "testRunName": "regression-run-v1.10",
      "reporter": "okhotemskyi"
    }
  ],
  "total": 1
}
```
```

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

### GET /api/ping

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

A simple health check endpoint to verify server responsiveness.

```APIDOC
## GET /api/ping

### Description
Checks if the server is running and responsive.

### Method
GET

### Endpoint
/api/ping

### Response
#### Success Response (200)
- **pong** (string) - A simple string response indicating the server is active.

#### Response Example
```
pong
```
```

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

### Upload Result Archive - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response after successfully uploading a result archive, including details of the uploaded result and generated report.

```json
{
  "message": "Success",
  "data": {
    "resultID": "e7ed1c2a-6b24-421a-abb6-095fb62f9957",
    "createdAt": "2024-07-07T13:35:57.382Z",
    "project": "desktop",
    "reporter": "okhotemskyi",
    "appVersion": "1.2.2",
    "size": "1.2 MB",
    "generatedReport": {
      "reportId": "e7ed1c2a-6b24-421a-abb6-095fb62f9957",
      "reportUrl": "/api/serve/desktop/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html",
      "metadata": { "title": "title", "project": "desktop" }
    }
  },
  "status": 201
}
```

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

### Delete Report Folder - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response after successfully deleting a report folder.

```json
{
  "message": "Reports deleted successfully",
  "reportsIds": ["6a615fe1-2452-4867-9ae5-6ee68313aac6"]
}
```

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

### Delete Result by IDs - API Response

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Example response after successfully deleting result files.

```json
{
  "message": "Results files deleted successfully",
  "resultsIds": ["6a615fe1-2452-4867-9ae5-6ee68313aac6"]
}
```

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

### Get Single Report

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Retrieves detailed information about a specific report by its unique ID.

```APIDOC
## GET /api/report/{reportId}

### Description
Retrieves detailed information about a specific report by its unique ID, including test statistics, metadata, and the URL to view the HTML report.

### Method
GET

### Endpoint
/api/report/{reportId}

#### Path Parameters
- **reportId** (string) - Required - The unique identifier of the report to retrieve.

### Request Example
```bash
curl --location 'http://localhost:3000/api/report/8e9af87d-1d10-4729-aefd-3e92ee64d06c' \
  --header 'Authorization: my-api-token'
```

### Response
#### Success Response (200)
- **reportID** (string) - The unique identifier for the report.
- **createdAt** (string) - The timestamp when the report was created.
- **project** (string) - The project name associated with the report.
- **size** (string) - The size of the report in a human-readable format.
- **title** (string) - The title of the report.
- **reportUrl** (string) - The URL to access the HTML report.
- **metadata** (object) - Additional metadata about the report.
  - **playwrightVersion** (string) - The Playwright version used.
  - **testRun** (string) - Identifier for the test run.
- **stats** (object) - Statistics about the test run.
  - **passed** (integer) - Number of passed tests.
  - **failed** (integer) - Number of failed tests.
  - **skipped** (integer) - Number of skipped tests.
  - **flaky** (integer) - Number of flaky tests.

#### Response Example
```json
{
  "reportID": "8e9af87d-1d10-4729-aefd-3e92ee64d06c",
  "createdAt": "2024-05-06T16:52:45.017Z",
  "project": "regression",
  "size": "6.97 MB",
  "title": "Regression Tests",
  "reportUrl": "/api/serve/regression/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html",
  "metadata": {
    "playwrightVersion": "1.45.0",
    "testRun": "nightly-2024-05-06"
  },
  "stats": { "passed": 150, "failed": 2, "skipped": 5, "flaky": 1 }
}
```
```

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

### Get Server Info - API Request

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Retrieves statistics and status information about the Playwright Reports Server. The Authorization header is required.

```sh
curl --location 'http://localhost:3000/api/info' \
--header 'Authorization: <api-token>'
```

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

### List Generated Reports using cURL

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Use cURL to make a GET request to the `/api/report/list` endpoint to retrieve a list of generated reports. Ensure you include the 'Authorization' header with your API token.

```sh
curl --location --request GET 'http://localhost:3000/api/report/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: <api-token>'
```

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

### Get Single Report Details

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Retrieve detailed information about a specific report using its unique ID. This includes test statistics, metadata, and the URL to view the HTML report. An API token is required.

```bash
curl --location 'http://localhost:3000/api/report/8e9af87d-1d10-4729-aefd-3e92ee64d06c' \
  --header 'Authorization: my-api-token'
```

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

### Get Report Trend Data

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Retrieve the latest reports for trend analysis and visualization. Optionally filter by project to view trends for specific test suites. An API token is required.

```bash
curl --location 'http://localhost:3000/api/report/trend?project=regression' \
  --header 'Authorization: my-api-token'
```

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

### Deploy with Docker (Local Storage)

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Run the Playwright Reports Server using Docker with local file storage. Mount a host directory to persist data.

```bash
# Basic local storage deployment
docker run -p 3000:3000 \
  -v /path/on/host:/app/data \
  -e API_TOKEN='my-secret-token' \
  ghcr.io/cyborgtests/playwright-reports-server:latest
```

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

### List Unique Result Projects

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns all unique project names from uploaded results.

```bash
curl --location 'http://localhost:3000/api/result/projects' \
  --header 'Authorization: my-api-token'
```

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

### Deploy with Docker (S3 Storage)

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Deploy the Playwright Reports Server using Docker with S3-compatible storage. Configure S3 credentials and bucket details via environment variables.

```bash
# S3 storage deployment
docker run -p 3000:3000 \
  -e API_TOKEN='my-secret-token' \
  -e DATA_STORAGE='s3' \
  -e S3_ENDPOINT='s3.amazonaws.com' \
  -e S3_REGION='us-east-1' \
  -e S3_BUCKET='my-reports-bucket' \
  -e S3_ACCESS_KEY='AKIAIOSFODNN7EXAMPLE' \
  -e S3_SECRET_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' \
  ghcr.io/cyborgtests/playwright-reports-server:latest
```

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

### Update UI Configuration via API

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Use this curl command to patch the server's configuration, including title, logo, favicon, and header links. Ensure you replace YOUR_TOKEN with your actual authentication token.

```sh
curl --location --request PATCH 'localhost:3000/api/config' \
  --header 'Authorization: YOUR_TOKEN' \
  --form 'title="YOUR_TITLE"' \
  --form 'logo=@"PATH_TO_YOUR_LOGO"' \
  --form 'favicon=@"PATH_TO_YOUR_FAVICON"' \
  --form 'headerLinks="{\"someLink\": \"https://example.com\", \"github\": \"https://github.com/CyborgTests\"}"'
```

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

### Docker Deployment

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Instructions for running the Playwright Reports Server using Docker, with and without external S3 storage configuration.

```APIDOC
## Docker Usage

### Basic Docker Run

To run the server using Docker with default settings:

```sh
docker run -p 3000:3000 -v /path/on/host:/app/data ghcr.io/cyborgtests/playwright-reports-server:latest
```

### Docker Run with S3 Storage

For external S3 storage, pass the necessary environment variables:

```sh
docker run -p 3000:3000 \
  -e STORAGE_TYPE=s3 \
  -e S3_ENDPOINT="<your-endpoint>" \
  -e S3_REGION="<your-region>" \
  -e S3_BUCKET="<your-bucket>" \
  -e S3_ACCESS_KEY_ID="<your-access-key>" \
  -e S3_SECRET_ACCESS_KEY="<your-secret-key>" \
  ghcr.io/cyborgtests/playwright-reports-server:latest
```

**Note**: Ensure the `/data` volume is persisted to retain configuration and generated reports.
```

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

### Configure Environment Variables

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Set environment variables or use a .env file to configure the server's authentication, storage, S3, and data expiration settings. For S3 storage, ensure all S3-specific variables are correctly set.

```bash
# Authentication
API_TOKEN='my-secret-api-token'          # Enable API authorization
AUTH_SECRET='generated-secret-key'        # JWT encryption secret
UI_AUTH_EXPIRE_HOURS='2'                  # Auth session duration

# Storage
DATA_STORAGE='fs'                         # 'fs' for local, 's3' for S3-compatible
USE_SERVER_CACHE='false'                  # Enable in-memory caching

# S3 Configuration (when DATA_STORAGE=s3)
S3_ENDPOINT='s3.amazonaws.com'
S3_REGION='us-east-1'
S3_ACCESS_KEY='your-access-key'
S3_SECRET_KEY='your-secret-key'
S3_BUCKET='playwright-reports-server'
S3_PORT=9000                              # Optional, for self-hosted
S3_BATCH_SIZE=10                          # Concurrent S3 requests

# Data Expiration
RESULT_EXPIRE_DAYS=30                     # Auto-delete results after N days
RESULT_EXPIRE_CRON_SCHEDULE='33 3 * * *'  # When to run cleanup
REPORT_EXPIRE_DAYS=90                     # Auto-delete reports after N days
REPORT_EXPIRE_CRON_SCHEDULE='44 4 * * *'  # When to run cleanup
```

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

### List Uploaded Blob Results

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns a paginated list of uploaded blob results. Supports filtering by project, tags, search, and date range.

```bash
# Basic list
curl --location 'http://localhost:3000/api/result/list' \
  --header 'Authorization: my-api-token'
```

```bash
# With filters
curl --location 'http://localhost:3000/api/result/list?project=regression&tags=environment:staging,reporter:ci&search=nightly&limit=20&offset=0' \
  --header 'Authorization: my-api-token'
```

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

### List All Reports (Basic)

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Use this command to retrieve a paginated list of all generated Playwright HTML reports stored on the server. An API token is required for authorization.

```bash
curl --location 'http://localhost:3000/api/report/list' \
  --header 'Authorization: my-api-token'
```

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

### Update Server Configuration

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Use this cURL command to update server settings such as UI branding and header links. Ensure you replace placeholders with your actual values.

```bash
curl --location --request PATCH 'http://localhost:3000/api/config' \
  --header 'Authorization: my-api-token' \
  --form 'title="My Custom Reports"' \
  --form 'logo=@"/path/to/logo.svg"' \
  --form 'favicon=@"/path/to/favicon.ico"' \
  --form 'headerLinks="{\"github\": \"https://github.com/myorg\", \"slack\": \"https://myorg.slack.com\"}"' \
  --form 'resultExpireDays="30"' \
  --form 'reportExpireDays="90"'
```

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

### List Reports with Pagination and Filtering

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Retrieve a paginated list of reports with options to filter by project, search term, and date range. This is useful for targeted queries. Requires an API token.

```bash
curl --location 'http://localhost:3000/api/report/list?project=regression&limit=10&offset=0&search=smoke&dateFrom=2024-01-01&dateTo=2024-12-31' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: my-api-token'
```

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

### Run Playwright Reports Server with Docker

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Use this command to run the server locally. Ensure port 3000 is available and map a local directory for data persistence.

```sh
docker run -p 3000:3000 -v /path/on/host:/app/data ghcr.io/cyborgtests/playwright-reports-server:latest
```

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

### List Result Projects

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns all unique project names from uploaded results.

```APIDOC
## GET /api/result/projects

### Description
Returns all unique project names from uploaded results.

### Method
GET

### Endpoint
/api/result/projects

### Response
#### Success Response (200)
- (array of strings) - A list of unique project names.

#### Response Example
```json
["regression", "smoke", "e2e", "mobile"]
```
```

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

### List All Report Projects

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Fetch a list of all unique project names from existing reports. This is useful for filtering and navigation within the UI. An API token is required.

```bash
curl --location 'http://localhost:3000/api/report/projects' \
  --header 'Authorization: my-api-token'
```

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

### Server Info

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns storage statistics including total data size, number of reports and results.

```APIDOC
## GET /api/info

### Description
Returns storage statistics including total data size, number of reports and results.

### Method
GET

### Endpoint
/api/info

### Response
#### Success Response (200)
- **dataFolderSizeinMB** (string) - The size of the data folder in MB.
- **numOfResults** (integer) - The total number of results.
- **resultsFolderSizeinMB** (string) - The size of the results folder in MB.
- **numOfReports** (integer) - The total number of reports.
- **reportsFolderSizeinMB** (string) - The size of the reports folder in MB.

#### Response Example
```json
{
  "dataFolderSizeinMB": "156.32 MB",
  "numOfResults": 42,
  "resultsFolderSizeinMB": "84.12 MB",
  "numOfReports": 15,
  "reportsFolderSizeinMB": "72.20 MB"
}
```
```

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

### Run Playwright Reports Server with Docker and S3 Storage

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Configure the server to use external S3 storage by providing the necessary environment variables. Replace placeholders with your S3 credentials and endpoint details.

```sh
docker run -p 3000:3000 \
  -e STORAGE_TYPE=s3 \
  -e S3_ENDPOINT="<your-endpoint>" \
  -e S3_REGION="<your-region>" \
  -e S3_BUCKET="<your-bucket>" \
  -e S3_ACCESS_KEY_ID="<your-access-key>" \
  -e S3_SECRET_ACCESS_KEY="<your-secret-key>" \
  ghcr.io/cyborgtests/playwright-reports-server:latest
```

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

### List Existing Results - API Request

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Retrieves a list of all currently existing raw result zip files on the server. No request body is needed.

```sh
curl --location 'http://localhost:3000/api/result/list'
```

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

### Upload Result with Presigned URL (S3)

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

For S3 storage, pass the file content length to receive a presigned URL for direct upload, reducing server load.

```bash
curl --location --request PUT 'http://localhost:3000/api/result/upload?fileContentLength=10738538' \
  --header 'Authorization: my-api-token' \
  --form 'file=@"./blob-report/report.zip"' \
  --form 'project="desktop"'
```

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

### UI White-label Configuration API

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

This endpoint allows customization of the application's UI elements such as title, logo, favicon, and header links.

```APIDOC
## UI White-label Configuration API

### PATCH /api/config

This endpoint allows you to update the UI configuration of the Playwright Reports Server. It accepts form-data and is used to customize the application's appearance.

### Method
PATCH

### Endpoint
`/api/config`

### Parameters
#### Request Body
- **title** (string) - Optional - The custom title for the application.
- **logo** (file) - Optional - The custom logo image file (e.g., SVG, PNG).
- **favicon** (file) - Optional - The custom favicon image file.
- **headerLinks** (string) - Optional - A JSON string representing an object where keys are link names and values are URLs. Example: `{"someLink": "https://example.com", "github": "https://github.com/CyborgTests"}`

### Request Example
```sh
curl --location --request PATCH 'localhost:3000/api/config' \
  --header 'Authorization: YOUR_TOKEN' \
  --form 'title="YOUR_TITLE"' \
  --form 'logo=@"PATH_TO_YOUR_LOGO"' \
  --form 'favicon=@"PATH_TO_YOUR_FAVICON"' \
  --form 'headerLinks="{\"someLink\": \"https://example.com\", \"github\": \"https://github.com/CyborgTests\"}"' 
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the configuration was updated successfully.

#### Response Example
```json
{
  "message": "Configuration updated successfully."
}
```

### Notes on Header Links
- The `headerLinks` parameter should be a JSON string representing an object.
- Keys in the `headerLinks` object are the names of the links.
- Values are the external URLs for the links.
- Predefined logos exist for `telegram`, `github`, `discord`, `bitbucket`, `slack`. If a logo for a link name is not found, a generic icon will be used.

### Configuration File Persistence

Configuration changes are saved to the `/data/` folder. To ensure changes persist across server restarts or redeployments, this directory should be mounted as a volume in your Docker setup.
```

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

### Upload Result Archive with Shard Information - API Request

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Uploads a result archive and triggers automatic report generation when all shards complete. Requires 'shardCurrent', 'shardTotal', and 'triggerReportGeneration=true' as form keys.

```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'shardCurrent="1"' \
--form 'shardTotal="4"' \
--form 'triggerReportGeneration="true"'
```

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

### List Results

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns a paginated list of uploaded blob results (raw test data before report generation). Supports filtering by project, tags, search, and date range.

```APIDOC
## GET /api/result/list

### Description
Returns a paginated list of uploaded blob results (raw test data before report generation). Supports filtering by project, tags, search, and date range.

### Method
GET

### Endpoint
/api/result/list

### Parameters
#### Query Parameters
- **project** (string) - Optional - Filter results by project name.
- **tags** (string) - Optional - Filter results by tags (e.g., `environment:staging,reporter:ci`).
- **search** (string) - Optional - Search term for results.
- **limit** (integer) - Optional - The maximum number of results to return per page. Defaults to 20.
- **offset** (integer) - Optional - The number of results to skip for pagination. Defaults to 0.

### Request Example
```bash
# Basic list
curl --location 'http://localhost:3000/api/result/list' \
  --header 'Authorization: my-api-token'

# With filters
curl --location 'http://localhost:3000/api/result/list?project=regression&tags=environment:staging,reporter:ci&search=nightly&limit=20&offset=0' \
  --header 'Authorization: my-api-token'
```

### Response
#### Success Response (200)
- **results** (array) - A list of uploaded blob results.
  - **resultID** (string) - The unique identifier for the result.
  - **createdAt** (string) - The timestamp when the result was created.
  - **size** (string) - The size of the uploaded file.
  - **sizeBytes** (integer) - The size of the uploaded file in bytes.
  - **project** (string) - The project name.
  - **testRun** (string) - The test run identifier.
  - **reporter** (string) - The reporter name.
  - **environment** (string) - The environment.
- **total** (integer) - The total number of results available.

#### Response Example
```json
{
  "results": [
    {
      "resultID": "a7beb04b-f190-4fbb-bebd-58b2c776e6c3",
      "createdAt": "2024-05-06T16:40:33.021Z",
      "size": "1.93 MB",
      "sizeBytes": 2024089,
      "project": "regression",
      "testRun": "nightly-2024-05-06",
      "reporter": "ci-pipeline",
      "environment": "staging"
    }
  ],
  "total": 156
}
```
```

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

### Health Check Endpoint

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Simple health check endpoint for monitoring and load balancers.

```bash
curl --location 'http://localhost:3000/api/ping'
```

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

### Generate Report from Blob Results

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Create a new HTML report by merging multiple blob results. This is essential for combining results from sharded test runs into a single consolidated report. Requires project details, result IDs, and API token.

```bash
curl --location --request POST 'http://localhost:3000/api/report/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: my-api-token' \
  --data '{ \
    "project": "regression", \
    "resultsIds": [ \
      "b1d29907-7efa-48e8-a8d1-db49cf5c2998", \
      "a7beb04b-f190-4fbb-bebd-58b2c776e6c3", \
      "c3d4e5f6-7890-1234-abcd-ef1234567890" \
    ], \
    "playwrightVersion": "1.45.0", \
    "testRun": "ci-build-1234" \
  }'
```

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

### List Report Projects

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Retrieves a list of all unique project names from existing reports.

```APIDOC
## GET /api/report/projects

### Description
Returns all unique project names from existing reports for filtering and navigation in the UI.

### Method
GET

### Endpoint
/api/report/projects

### Request Example
```bash
curl --location 'http://localhost:3000/api/report/projects' \
  --header 'Authorization: my-api-token'
```

### Response
#### Success Response (200)
- Returns an array of strings, where each string is a unique project name.

#### Response Example
```json
["regression", "smoke", "e2e", "integration"]
```
```

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

### List Unique Result Tags

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns all unique metadata tags from results, optionally filtered by project. Useful for building filter UIs.

```bash
curl --location 'http://localhost:3000/api/result/tags?project=regression' \
  --header 'Authorization: my-api-token'
```

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

### Upload Result Archive with Metadata - API Request

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Uploads a result archive with additional metadata such as project, reporter, and app version. The Authorization header and 'file' form key are required.

```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'project="desktop"' \
--form 'reporter="okhotemskyi"' \
--form 'appVersion="1.2.2"'
```

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

### Generate Authorization Secret

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Use these commands to generate a new secret for JWT token generation when UI authorization is enabled.

```bash
# You can generate a new secret on the command line with:
npm exec auth secret
# OR
openssl rand -base64 32
```

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

### PUT /api/result/upload

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Uploads a result archive (.zip) to the server.

```APIDOC
## PUT /api/result/upload

### Description
Uploads a result archive (output of Playwright's blob reporter) to the server. Custom form keys can be added for metadata. Supports direct upload via S3 presigned URL using `fileContentLength` query parameter.

### Method
PUT

### Endpoint
/api/result/upload

### Parameters
#### Query Parameters
- **fileContentLength** (integer) - Optional - Specifies the content length of the file for direct upload using presigned URLs (S3 storage only).

#### Request Body
- **file** (file) - Required - The result archive (.zip file).
- **project** (string) - Optional - Custom metadata: project name.
- **reporter** (string) - Optional - Custom metadata: reporter name.
- **appVersion** (string) - Optional - Custom metadata: application version.
- **shardCurrent** (string) - Optional - Used for sharded test runs: the current shard number.
- **shardTotal** (string) - Optional - Used for sharded test runs: the total number of shards.
- **triggerReportGeneration** (string) - Optional - Set to `"true"` to automatically trigger report generation when all shards complete.
- **testRun** (string) - Optional - Used in conjunction with sharding to identify the test run.

### Request Example (Basic Upload)
```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"'
```

### Request Example (With Metadata)
```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'project="desktop"' \
--form 'reporter="okhotemskyi"' \
--form 'appVersion="1.2.2"'
```

### Request Example (S3 Presigned URL)
```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload?fileContentLength=10738538' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'project="desktop"' \
--form 'reporter="okhotemskyi"' \
--form 'appVersion="1.2.2"'
```

### Request Example (Sharded Upload)
```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'shardCurrent="1"' \
--form 'shardTotal="4"' \
--form 'triggerReportGeneration="true"'
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **data** (object) - Details of the uploaded result.
  - **resultID** (string) - The unique identifier for the uploaded result.
  - **createdAt** (string) - The timestamp when the result was created.
  - **project** (string) - The project associated with the result.
  - **reporter** (string) - The reporter used.
  - **appVersion** (string) - The application version.
  - **size** (string) - The size of the uploaded result.
  - **generatedReport** (object) - Information about the generated report, if applicable.
    - **reportId** (string) - The ID of the generated report.
    - **reportUrl** (string) - The URL to access the generated report.
    - **metadata** (object) - Metadata associated with the report.
- **status** (integer) - HTTP status code.

#### Response Example
```json
{
  "message": "Success",
  "data": {
    "resultID": "e7ed1c2a-6b24-421a-abb6-095fb62f9957",
    "createdAt": "2024-07-07T13:35:57.382Z",
    "project": "desktop",
    "reporter": "okhotemskyi",
    "appVersion": "1.2.2",
    "size": "1.2 MB",
    "generatedReport": {
      "reportId": "e7ed1c2a-6b24-421a-abb6-095fb62f9957",
      "reportUrl": "/api/serve/desktop/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html",
      "metadata": { "title": "title", "project": "desktop" }
    }
  },
  "status": 201
}
```
```

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

### Expiration Task Configuration

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Environment variables to configure the expiration of report and result files. Decimal values are supported for granular time periods (e.g., 0.25 for 6 hours).

```env
RESULT_EXPIRE_DAYS
RESULT_EXPIRE_CRON_SCHEDULE
REPORT_EXPIRE_DAYS
REPORT_EXPIRE_CRON_SCHEDULE
```

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

### List Result Tags

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Returns all unique metadata tags from results, optionally filtered by project. Useful for building filter UIs.

```APIDOC
## GET /api/result/tags

### Description
Returns all unique metadata tags from results, optionally filtered by project. Useful for building filter UIs.

### Method
GET

### Endpoint
/api/result/tags

### Parameters
#### Query Parameters
- **project** (string) - Optional - Filter tags by project name.

### Request Example
```bash
curl --location 'http://localhost:3000/api/result/tags?project=regression' \
  --header 'Authorization: my-api-token'
```

### Response
#### Success Response (200)
- (array of strings) - A list of unique metadata tags.

#### Response Example
```json
[
  "environment: staging",
  "environment: production",
  "reporter: ci-pipeline",
  "appVersion: 1.2.2"
]
```
```

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

### Generate Report

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Creates a new HTML report by merging multiple blob results, useful for consolidating sharded test runs.

```APIDOC
## POST /api/report/generate

### Description
Creates a new HTML report by merging multiple blob results together. Essential for combining results from sharded test runs into a single consolidated report.

### Method
POST

### Endpoint
/api/report/generate

#### Request Body
- **project** (string) - Required - The project name for the report.
- **resultsIds** (array of strings) - Required - A list of IDs of the blob results to merge.
- **playwrightVersion** (string) - Optional - The Playwright version used for the test run.
- **testRun** (string) - Optional - An identifier for the test run.

### Request Example
```bash
curl --location --request POST 'http://localhost:3000/api/report/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: my-api-token' \
  --data '{ 
    "project": "regression",
    "resultsIds": [
      "b1d29907-7efa-48e8-a8d1-db49cf5c2998",
      "a7beb04b-f190-4fbb-bebd-58b2c776e6c3",
      "c3d4e5f6-7890-1234-abcd-ef1234567890"
    ],
    "playwrightVersion": "1.45.0",
    "testRun": "ci-build-1234"
  }'
```

### Response
#### Success Response (200)
- **reportId** (string) - The ID of the newly generated report.
- **reportUrl** (string) - The URL to access the generated HTML report.
- **metadata** (object) - Metadata associated with the generated report.
  - **project** (string) - The project name.
  - **playwrightVersion** (string) - The Playwright version used.
  - **testRun** (string) - The test run identifier.

#### Response Example
```json
{
  "reportId": "8e9af87d-1d10-4729-aefd-3e92ee64d06c",
  "reportUrl": "/api/serve/regression/8e9af87d-1d10-4729-aefd-3e92ee64d06c/index.html",
  "metadata": {
    "project": "regression",
    "playwrightVersion": "1.45.0",
    "testRun": "ci-build-1234"
  }
}
```
```

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

### Upload Playwright Result Blob

Source: https://context7.com/cyborgtests/playwright-reports-server/llms.txt

Uploads a Playwright blob report zip file for storage. Supports custom metadata fields and automatic report generation when all shards complete.

```bash
# Basic upload
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
  --header 'Authorization: my-api-token' \
  --form 'file=@"./blob-report/report.zip"'
```

```bash
# Upload with metadata
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
  --header 'Authorization: my-api-token' \
  --form 'file=@"./blob-report/report.zip"' \
  --form 'project="desktop"' \
  --form 'reporter="ci-pipeline"' \
  --form 'appVersion="1.2.2"' \
  --form 'environment="staging"'
```

```bash
# Upload with sharding and auto-generate report
curl --location --request PUT 'http://localhost:3000/api/result/upload' \
  --header 'Authorization: my-api-token' \
  --form 'file=@"./blob-report/report.zip"' \
  --form 'project="regression"' \
  --form 'testRun="nightly-2024-05-06"' \
  --form 'shardCurrent="1"' \
  --form 'shardTotal="4"' \
  --form 'triggerReportGeneration="true"'
```

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

### Upload Result Archive with Direct S3 Upload - API Request

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Uploads a result archive using a presigned URL for direct S3 upload. Requires the 'fileContentLength' query parameter and the Authorization header.

```sh
curl --location --request PUT 'http://localhost:3000/api/result/upload?fileContentLength=10738538' \
--header 'Authorization: <api-token>' \
--form 'file=@"/path/to/file"' \
--form 'project="desktop"' \
--form 'reporter="okhotemskyi"' \
--form 'appVersion="1.2.2"'
```

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

### S3 Storage Environment Variables

Source: https://github.com/cyborgtests/playwright-reports-server/blob/main/readme.md

Environment variables required to configure S3-compatible object storage for Playwright Reports Server. Ensure your S3 credentials have read/write access.

```env
DATA_STORAGE=s3
S3_ENDPOINT=<your-s3-endpoint> # just a hostname, like my.minio.com
S3_REGION=<your-s3-region>
S3_ACCESS_KEY=<your-access-key>
S3_SECRET_KEY=<your-secret-key>
S3_BUCKET=<your-s3-bucket-name> # optional, by default "playwright-reports-server"
S3_PORT=9000 # optional, specify if you have self-hosted instance exposed via custom port
S3_BATCH_SIZE=10 # optional, a number of concurrent requests to s3
```