### Start Medama API Development Server (Bash)

Source: https://github.com/medama-io/medama/blob/main/core/README.md

This command initiates the Medama API development server. It requires Taskfile to be installed and passes the 'start' command as an argument to the 'dev' task.

```bash
task dev -- start
```

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

### Start API Server with Taskfile

Source: https://github.com/medama-io/medama/blob/main/CONTRIBUTING.md

This command starts the API server for the core project. It requires navigating to the './core' directory and executing the 'dev -- start' command using Taskfile.

```bash
cd ./core
task dev -- start
```

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

### GET /websites

Source: https://context7.com/medama-io/medama/llms.txt

Retrieve all websites registered for the current user. Optionally include a summary with visitor counts.

```APIDOC
## GET /websites

### Description
Retrieve all websites registered for the current user. Optionally include a summary with visitor counts.

### Method
GET

### Endpoint
`/websites`

### Parameters
#### Query Parameters
- **summary** (boolean) - Optional - If true, include visitor counts in the response.

### Request Example
```bash
# List all websites
curl -X GET "http://localhost:8080/websites" \
  -b cookies.txt

# List with visitor summary
curl -X GET "http://localhost:8080/websites?summary=true" \
  -b cookies.txt
```

### Response
#### Success Response (200 OK)
- **hostname** (string) - The hostname of the website.
- **summary** (object) - Optional - An object containing visitor statistics if `summary=true` was provided.
  - **visitors** (integer) - The total number of visitors.

#### Response Example
```json
[
  {
    "hostname": "example.com",
    "summary": {
      "visitors": 1250
    }
  }
]
```
```

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

### Run Medama API Tests (Bash)

Source: https://github.com/medama-io/medama/blob/main/core/README.md

This command executes the test suite for the Medama API. It relies on Taskfile being installed to manage the testing process.

```bash
task test
```

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

### Start Dashboard Dev Server with Taskfile

Source: https://github.com/medama-io/medama/blob/main/CONTRIBUTING.md

This command initiates the development server for the dashboard with Hot Module Replacement (HMR). It involves changing the directory to './dashboard' and running the 'dev' command via Taskfile.

```bash
cd ./dashboard
task dev
```

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

### Get Server Resource Usage via API

Source: https://context7.com/medama-io/medama/llms.txt

This snippet demonstrates how to retrieve server resource usage statistics, including CPU, memory, and disk utilization, by sending a GET request to the /user/usage endpoint. Authentication is handled via cookies. The expected response format is JSON.

```bash
curl -X GET "http://localhost:8080/user/usage" \
  -b cookies.txt
```

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

### GET /website/{hostname}/summary

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves an overview of website statistics including visitors, pageviews, bounce rate, and average duration. Supports time periods and comparison with previous periods.

```APIDOC
## GET /website/{hostname}/summary

### Description
Get an overview of website statistics including visitors, pageviews, bounce rate, and average duration. Supports time periods and comparison with previous periods.

### Method
GET

### Endpoint
`/website/{hostname}/summary`

### Query Parameters
- **start** (string) - Optional - Start date/time for the statistics period (ISO 8601 format).
- **end** (string) - Optional - End date/time for the statistics period (ISO 8601 format).
- **previous** (boolean) - Optional - If true, includes statistics for the previous period for comparison.
- **interval** (string) - Optional - Breakdown interval for statistics (e.g., "minute", "hour", "day", "week", "month").

### Request Example
```bash
# Get summary for all time
curl -X GET "http://localhost:8080/website/example.com/summary" \
  -b cookies.txt

# Get summary for specific date range with previous period comparison
curl -X GET "http://localhost:8080/website/example.com/summary?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&previous=true" \
  -b cookies.txt

# Get summary with interval breakdown (day)
curl -X GET "http://localhost:8080/website/example.com/summary?start=2024-01-01T00:00:00Z&end=2024-01-07T23:59:59Z&interval=day" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **current** (object) - Statistics for the current period.
  - **visitors** (integer) - Number of unique visitors.
  - **pageviews** (integer) - Total number of page views.
  - **bounce_percentage** (float) - Percentage of single-page sessions.
  - **duration** (integer) - Average session duration in milliseconds.
- **previous** (object) - Statistics for the previous period (if `previous=true`). Structure is the same as `current`.
- **interval** (array) - Array of statistics broken down by the specified interval (if `interval` is provided).
  - Each object in the array contains date/time and the corresponding metrics.

#### Response Example
```json
{
  "current": {
    "visitors": 1250,
    "pageviews": 3400,
    "bounce_percentage": 45.2,
    "duration": 125000
  },
  "previous": {
    "visitors": 980,
    "pageviews": 2800,
    "bounce_percentage": 48.5,
    "duration": 110000
  },
  "interval": [
    {"date": "2024-01-01", "visitors": 180, "pageviews": 490, "bounce_percentage": 40.0, "duration": 130000},
    {"date": "2024-01-02", "visitors": 195, "pageviews": 520, "bounce_percentage": 41.0, "duration": 135000}
  ]
}
```
```

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

### GET /website/{hostname}/pages

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves statistics for individual pages including visitor counts, pageviews, bounce rates, and time on page.

```APIDOC
## GET /website/{hostname}/pages

### Description
Get statistics for individual pages including visitor counts, pageviews, bounce rates, and time on page.

### Method
GET

### Endpoint
`/website/{hostname}/pages`

### Query Parameters
- **start** (string) - Optional - Start date/time for the statistics period (ISO 8601 format).
- **end** (string) - Optional - End date/time for the statistics period (ISO 8601 format).
- **limit** (integer) - Optional - Maximum number of pages to return.
- **path** (object) - Optional - Filter by path. Can use operators like `starts_with`.
  - **path[starts_with]** (string) - Filter pages whose path starts with the given string.

### Request Example
```bash
# Get page statistics
curl -X GET "http://localhost:8080/website/example.com/pages?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&limit=10" \
  -b cookies.txt

# Filter by specific path prefix
curl -X GET "http://localhost:8080/website/example.com/pages?path[starts_with]=/blog" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- An array of page statistics objects.
  - **path** (string) - The URL path of the page.
  - **visitors** (integer) - Number of unique visitors to this page.
  - **visitors_percentage** (float) - Percentage of total visitors that visited this page.
  - **pageviews** (integer) - Total number of views for this page.
  - **pageviews_percentage** (float) - Percentage of total pageviews for this page.
  - **bounce_percentage** (float) - Bounce rate for this page.
  - **duration** (integer) - Average time spent on this page in milliseconds.

#### Response Example
```json
[
  {
    "path": "/blog/post-1",
    "visitors": 450,
    "visitors_percentage": 36.0,
    "pageviews": 890,
    "pageviews_percentage": 26.2,
    "bounce_percentage": 42.5,
    "duration": 85000
  }
]
```
```

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

### Get Device & Browser Stats - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Fetches statistics related to visitor browsers, operating systems, and device types. Authentication is handled through cookies.txt.

```bash
# Get browser statistics
curl -X GET "http://localhost:8080/website/example.com/browsers" \
  -b cookies.txt

# Get operating system statistics
curl -X GET "http://localhost:8080/website/example.com/os" \
  -b cookies.txt

# Get device type statistics (desktop, mobile, tablet)
curl -X GET "http://localhost:8080/website/example.com/devices" \
  -b cookies.txt
```

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

### Run Medama Analytics with Docker

Source: https://context7.com/medama-io/medama/llms.txt

This snippet shows how to run the Medama Analytics application using Docker. It includes options for detached mode, naming the container, port mapping, volume mounting for persistent data, and setting the server port via an environment variable. The example uses the latest image from ghcr.io/medama-io/medama.

```bash
docker run -d \
  --name medama \
  -p 8080:8080 \
  -v medama-data:/app/data \
  -e PORT=8080 \
  ghcr.io/medama-io/medama:latest
```

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

### Get Website Summary Statistics (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves an overview of website statistics, including visitors, pageviews, bounce rate, and duration. Supports filtering by date range, comparing with previous periods, and breaking down data by intervals (day, week, month).

```bash
# Get summary for all time
curl -X GET "http://localhost:8080/website/example.com/summary" \
  -b cookies.txt
```

```bash
# Get summary for specific date range with previous period comparison
curl -X GET "http://localhost:8080/website/example.com/summary?"
  "start=2024-01-01T00:00:00Z&"
  "end=2024-01-31T23:59:59Z&"
  "previous=true" \
  -b cookies.txt
```

```bash
# Get summary with interval breakdown (minute, hour, day, week, month)
curl -X GET "http://localhost:8080/website/example.com/summary?"
  "start=2024-01-01T00:00:00Z&"
  "end=2024-01-07T23:59:59Z&"
  "interval=day" \
  -b cookies.txt
```

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

### Get Referrer Statistics (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves traffic source statistics, showing where visitors originate from. Supports grouping referrers by domain or providing full URLs. Filtering by date range is also available.

```bash
# Get referrer statistics (grouped by domain)
curl -X GET "http://localhost:8080/website/example.com/referrers?"
  "start=2024-01-01T00:00:00Z&"
  "end=2024-01-31T23:59:59Z&"
  "grouped=true" \
  -b cookies.txt
```

```bash
# Get ungrouped referrer URLs
curl -X GET "http://localhost:8080/website/example.com/referrers?grouped=false" \
  -b cookies.txt
```

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

### GET /website/{hostname}/referrers

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves traffic source statistics showing where visitors come from. Supports grouped (by domain) or ungrouped (full URLs) results.

```APIDOC
## GET /website/{hostname}/referrers

### Description
Get traffic source statistics showing where visitors come from. Supports grouped (by domain) or ungrouped (full URLs) results.

### Method
GET

### Endpoint
`/website/{hostname}/referrers`

### Query Parameters
- **start** (string) - Optional - Start date/time for the statistics period (ISO 8601 format).
- **end** (string) - Optional - End date/time for the statistics period (ISO 8601 format).
- **grouped** (boolean) - Required - If true, referrers are grouped by domain. If false, returns full referrer URLs.

### Request Example
```bash
# Get referrer statistics (grouped by domain)
curl -X GET "http://localhost:8080/website/example.com/referrers?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&grouped=true" \
  -b cookies.txt

# Get ungrouped referrer URLs
curl -X GET "http://localhost:8080/website/example.com/referrers?grouped=false" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- An array of referrer statistics objects.
  - **referrer** (string) - The referrer domain (if `grouped=true`) or the full referrer URL (if `grouped=false`).
  - **visitors** (integer) - Number of visitors from this referrer.
  - **visitors_percentage** (float) - Percentage of total visitors from this referrer.
  - **pageviews** (integer) - Number of pageviews originating from this referrer.
  - **pageviews_percentage** (float) - Percentage of total pageviews originating from this referrer.

#### Response Example
```json
[
  {
    "referrer": "google.com",
    "visitors": 600,
    "visitors_percentage": 48.0,
    "pageviews": 1500,
    "pageviews_percentage": 44.1
  },
  {
    "referrer": "https://twitter.com/",
    "visitors": 150,
    "visitors_percentage": 12.0,
    "pageviews": 300,
    "pageviews_percentage": 8.8
  }
]
```
```

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

### Get UTM Campaign Statistics - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves statistics for UTM parameters like source, medium, and campaign to analyze marketing efforts. Requires authentication via cookies.txt.

```bash
# Get UTM source statistics
curl -X GET "http://localhost:8080/website/example.com/sources" \
  -b cookies.txt

# Get UTM medium statistics
curl -X GET "http://localhost:8080/website/example.com/mediums" \
  -b cookies.txt

# Get UTM campaign statistics
curl -X GET "http://localhost:8080/website/example.com/campaigns?"
  start=2024-01-01T00:00:00Z&\
  end=2024-01-31T23:59:59Z" \
  -b cookies.txt
```

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

### GET /event/ping

Source: https://context7.com/medama-io/medama/llms.txt

Pings the event tracking service. Useful for checking connectivity and receiving user/cache information.

```APIDOC
## GET /event/ping

### Description
Pings the event tracking service. This endpoint can be used to check if the service is reachable and to receive information about the user's session, including Last-Modified and Cache-Control headers. Subsequent requests will automatically include the If-Modified-Since header.

### Method
GET

### Endpoint
`/event/ping`

### Query Parameters
- **u** (string) - Required - The URL of the page being tracked.

### Request Example
```bash
curl -X GET "http://localhost:8080/event/ping?u=example.com/page" \
  -H "Content-Type: text/plain" \
  -H "If-Modified-Since: Tue, 15 Jan 2024 00:00:00 GMT"
```

### Response
#### Success Response (200)
- **Last-Modified** (string) - The last modified date of the resource.
- **Cache-Control** (string) - Cache control directives.

#### Response Example
(Headers only, no body content specified in the provided text)
```

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

### Get Page Statistics (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves statistics for individual pages, including visitor counts, pageviews, bounce rates, and time on page. Supports filtering by date range, limiting results, and filtering by URL path.

```bash
# Get page statistics
curl -X GET "http://localhost:8080/website/example.com/pages?"
  "start=2024-01-01T00:00:00Z&"
  "end=2024-01-31T23:59:59Z&"
  "limit=10" \
  -b cookies.txt
```

```bash
# Filter by specific path
curl -X GET "http://localhost:8080/website/example.com/pages?"
  "path[starts_with]=/blog" \
  -b cookies.txt
```

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

### Get Geographic & Language Stats - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Retrieves visitor statistics broken down by country and language. Country detection is inferred from timezone for privacy. Requires cookies.txt for authentication.

```bash
# Get country statistics
curl -X GET "http://localhost:8080/website/example.com/countries" \
  -b cookies.txt

# Get language statistics (base language names)
curl -X GET "http://localhost:8080/website/example.com/languages" \
  -b cookies.txt

# Get language statistics with locale/dialect details
curl -X GET "http://localhost:8080/website/example.com/languages?locale=true" \
  -b cookies.txt
```

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

### Get Custom Property Statistics - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Fetches statistics for custom event properties defined via tracker data attributes or custom events. Supports querying specific property values. Authentication via cookies.txt.

```bash
# Get all custom property names
curl -X GET "http://localhost:8080/website/example.com/properties" \
  -b cookies.txt

# Get values for a specific property
curl -X GET "http://localhost:8080/website/example.com/properties?"
  prop_name[eq]=plan" \
  -b cookies.txt
```

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

### GET /event/ping

Source: https://context7.com/medama-io/medama/llms.txt

The ping endpoint determines if a visitor is unique using browser caching. Returns "0" for unique users, "1" for returning users within the same day.

```APIDOC
## GET /event/ping

### Description
The ping endpoint determines if a visitor is unique using browser caching. Returns "0" for unique users, "1" for returning users within the same day.

### Method
GET

### Endpoint
`/event/ping`

### Parameters
#### Query Parameters
- **u** (string) - Required - The URL or identifier for the page being visited.

### Request Example
```bash
# Check if user is unique (first visit)
curl -X GET "http://localhost:8080/event/ping?u=example.com/page" \
  -H "Content-Type: text/plain"
```

### Response
#### Success Response (200 OK)
- **Response Body** (string) - "0" for unique users, "1" for returning users.
```

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

### List Websites in Medama

Source: https://context7.com/medama-io/medama/llms.txt

Retrieve a list of all registered websites for the current user. Optionally, include a summary of visitor counts for each website.

```bash
# List all websites
curl -X GET "http://localhost:8080/websites" \
  -b cookies.txt

# List with visitor summary
curl -X GET "http://localhost:8080/websites?summary=true" \
  -b cookies.txt

# Response: 200 OK
# [
#   {
#     "hostname": "example.com",
#     "summary": {
#       "visitors": 1250
#     }
#   }
# ]
```

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

### Run Medama Analytics with Custom Docker Configuration

Source: https://context7.com/medama-io/medama/llms.txt

This snippet demonstrates running Medama Analytics with Docker using custom environment variables for configuration. It allows setting the logger format, log level, demo mode, CORS origins, and specifies a custom path for data persistence. This provides more flexibility for production deployments.

```bash
docker run -d \
  --name medama \
  -p 8080:8080 \
  -v /path/to/data:/app/data \
  -e PORT=8080 \
  -e LOGGER=json \
  -e LEVEL=info \
  -e DEMO_MODE=false \
  -e CORS_ALLOWED_ORIGINS=https://example.com \
  ghcr.io/medama-io/medama:latest
```

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

### Manage User Account Settings - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Provides endpoints for managing user account settings, including username, password, and analytics preferences. Requires authentication via cookies.txt.

```bash
# Get current user info
curl -X GET "http://localhost:8080/user" \
  -b cookies.txt
```

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

### Filter Statistics with Query Operators - Bash

Source: https://context7.com/medama-io/medama/llms.txt

Demonstrates advanced filtering capabilities for statistics endpoints using various query parameter operators like 'eq', 'contains', 'in', and 'starts_with'. Authentication via cookies.txt.

```bash
# Filter operators available for string fields:
# - eq: Equal to
# - neq: Not equal to
# - contains: Contains substring
# - not_contains: Does not contain
# - starts_with: Starts with
# - not_starts_with: Does not start with
# - ends_with: Ends with
# - not_ends_with: Does not end with
# - in: In list (comma-separated)
# - not_in: Not in list

# Example: Get stats for pages starting with /blog but not /blog/drafts
curl -X GET "http://localhost:8080/website/example.com/pages?"
  path[starts_with]=/blog&\
  path[not_starts_with]=/blog/drafts" \
  -b cookies.txt

# Example: Get stats for Chrome or Firefox users only
curl -X GET "http://localhost:8080/website/example.com/summary?"
  browser[in]=Chrome,Firefox" \
  -b cookies.txt

# Example: Get stats excluding bot traffic from specific countries
curl -X GET "http://localhost:8080/website/example.com/summary?"
  country[not_in]=Unknown" \
  -b cookies.txt
```

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

### Add Website to Medama

Source: https://context7.com/medama-io/medama/llms.txt

Register a new website for analytics tracking via the Medama API. The hostname serves as the unique identifier for each website.

```bash
# Add a new website to track
curl -X POST "http://localhost:8080/websites" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "hostname": "example.com"
  }'

# Response: 201 Created
# {
#   "hostname": "example.com"
# }
```

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

### POST /websites

Source: https://context7.com/medama-io/medama/llms.txt

Register a new website for analytics tracking. The hostname is used as the unique identifier for the website.

```APIDOC
## POST /websites

### Description
Register a new website for analytics tracking. The hostname is used as the unique identifier for the website.

### Method
POST

### Endpoint
`/websites`

### Parameters
#### Request Body
- **hostname** (string) - Required - The hostname of the website to track.

### Request Example
```json
{
  "hostname": "example.com"
}
```

### Response
#### Success Response (201 Created)
- **hostname** (string) - The hostname of the newly registered website.

#### Response Example
```json
{
  "hostname": "example.com"
}
```
```

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

### Medama Server Environment Configuration

Source: https://context7.com/medama-io/medama/llms.txt

This section details the environment variables used to configure the Medama server. It covers essential settings like the HTTP port, logging format and level, database paths for user and analytics data, security settings such as CORS origins and demo mode, and optional configurations for automatic SSL and debugging.

```bash
# Server configuration
PORT=8080                              # HTTP server port (default: 8080)
LOGGER=json                            # Log format: json or pretty (default: json)
LEVEL=info                             # Log level: debug, info, warn, error (default: info)

# Database paths
APP_DATABASE_HOST=/app/data/me_app.db           # SQLite database for users/websites
ANALYTICS_DATABASE_HOST=/app/data/me_analytics.db  # DuckDB for analytics data

# Security settings
CORS_ALLOWED_ORIGINS=https://example.com,https://app.example.com  # Comma-separated allowed origins
DEMO_MODE=false                        # Enable demo mode (read-only)

# Optional: Auto SSL with Let's Encrypt
AUTO_SSL=example.com                   # Domain for automatic HTTPS
AUTO_SSL_EMAIL=admin@example.com       # Email for Let's Encrypt notifications

# Optional: Debugging
PROFILER=false                         # Enable /debug/pprof endpoints
```

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

### Send Page View Event (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Sends a page view event to the Medama API. This is typically done when a user loads a page. It includes details like the event type, beacon ID, URL, referrer, user context, and custom properties.

```bash
curl -X POST "http://localhost:8080/event/hit" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -d '{
    "e": "load",
    "b": "m5x7k9p2q",
    "u": "https://example.com/blog/post-1?utm_source=twitter",
    "r": "https://twitter.com/",
    "p": true,
    "q": true,
    "t": "America/New_York",
    "d": {
      "author": "John Doe",
      "category": "Technology"
    }
  }'
```

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

### Tracker Integration

Source: https://context7.com/medama-io/medama/llms.txt

Instructions on how to integrate the Medama JavaScript tracker into your website.

```APIDOC
## Tracker Integration

The tracker script is a lightweight JavaScript snippet that sends analytics events to your Medama server. It automatically tracks page views, time spent on page, and supports custom events via data attributes.

### Basic Tracker Integration

```html
<!-- Basic tracker integration - replace YOUR_DOMAIN with your Medama server domain -->
<script defer src="https://YOUR_DOMAIN/script.js"></script>

<!-- Or specify a custom API endpoint -->
<script defer src="https://YOUR_DOMAIN/script.js" data-api="api.example.com"></script>

<!-- Enable hash-based routing mode for SPAs using hash navigation -->
<script defer src="https://YOUR_DOMAIN/script.js" data-hash="true"></script>
```

### Tracker Script Variants

Medama provides multiple tracker script variants optimized for different use cases. Each variant adds specific functionality while keeping the bundle size minimal.

#### Default Tracker

*   **Description**: Basic page views and time tracking (~0.75KB gzipped).
*   **Usage**: 
    ```html
    <script defer src="https://YOUR_DOMAIN/script.js"></script>
    ```

#### Page Events Tracker

*   **Description**: Includes custom properties on page load (~0.87KB gzipped).
*   **Usage**: Add data attributes to elements.
    ```html
    <div data-m:load="plan=premium; source=homepage">Content</div>
    ```

#### Click Events Tracker

*   **Description**: Track click events with custom properties (~0.95KB gzipped).
*   **Usage**: Add data attributes to clickable elements.
    ```html
    <button data-m:click="action=signup; location=header">Sign Up</button>
    ```
```

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

### PATCH /websites/{hostname}

Source: https://context7.com/medama-io/medama/llms.txt

Update a website's hostname.

```APIDOC
## PATCH /websites/{hostname}

### Description
Update a website's hostname.

### Method
PATCH

### Endpoint
`/websites/{hostname}`

### Parameters
#### Path Parameters
- **hostname** (string) - Required - The current hostname of the website to update.

#### Request Body
- **hostname** (string) - Required - The new hostname for the website.

### Request Example
```bash
curl -X PATCH "http://localhost:8080/websites/example.com" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "hostname": "new-example.com"
  }'
```

### Response
#### Success Response (204 No Content)
No content is returned upon successful update.
```

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

### Server Resource Usage API

Source: https://context7.com/medama-io/medama/llms.txt

API to monitor server resource usage including CPU, memory, and disk statistics.

```APIDOC
## GET /user/usage

### Description
Retrieves current server resource usage statistics.

### Method
GET

### Endpoint
/user/usage

### Response
#### Success Response (200)
- **cpu** (object) - CPU usage statistics.
  - **usage** (number) - Percentage of CPU usage.
  - **cores** (integer) - Number of CPU cores.
  - **threads** (integer) - Number of CPU threads.
- **memory** (object) - Memory usage statistics.
  - **used** (integer) - Amount of memory used in bytes.
  - **total** (integer) - Total amount of memory in bytes.
- **disk** (object) - Disk usage statistics.
  - **used** (integer) - Amount of disk space used in bytes.
  - **total** (integer) - Total amount of disk space in bytes.

#### Response Example
```json
{
  "cpu": {
    "usage": 12.5,
    "cores": 4,
    "threads": 8
  },
  "memory": {
    "used": 536870912,
    "total": 8589934592
  },
  "disk": {
    "used": 10737418240,
    "total": 107374182400
  }
}
```
```

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

### User Settings JSON Schema

Source: https://github.com/medama-io/medama/blob/main/core/migrations/Schema.md

Defines the structure for user settings, including script type and language preferences. The 'script_type' can be 'default' or 'tagged-events', and 'language' currently only supports 'en'.

```json
{
    "script_type": string, // Comma separated string of script features. Can only include 'default' or 'tagged-events'.
    "language": string, // Only supports 'en' for now
}
```

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

### DELETE /websites/{hostname}

Source: https://context7.com/medama-io/medama/llms.txt

Delete a website from tracking.

```APIDOC
## DELETE /websites/{hostname}

### Description
Delete a website from tracking.

### Method
DELETE

### Endpoint
`/websites/{hostname}`

### Parameters
#### Path Parameters
- **hostname** (string) - Required - The hostname of the website to delete.

### Request Example
```bash
curl -X DELETE "http://localhost:8080/websites/example.com" \
  -b cookies.txt
```

### Response
#### Success Response (204 No Content)
No content is returned upon successful deletion.
```

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

### Update or Delete Website in Medama

Source: https://context7.com/medama-io/medama/llms.txt

Modify a website's hostname or remove a website from analytics tracking using the Medama API. These operations require authentication.

```bash
# Update website hostname
curl -X PATCH "http://localhost:8080/websites/example.com" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "hostname": "new-example.com"
  }'

# Delete a website
curl -X DELETE "http://localhost:8080/websites/example.com" \
  -b cookies.txt

# Response: 204 No Content
```

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

### Update User Settings via API

Source: https://context7.com/medama-io/medama/llms.txt

This snippet demonstrates how to update user settings, including username, password, and various blocking preferences, using a PATCH request to the /user endpoint. It requires a Content-Type header and sends user data in JSON format. Cookies are used for authentication.

```bash
curl -X PATCH "http://localhost:8080/user" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "username": "newusername",
    "password": "new_secure_password",
    "settings": {
      "blockAbusiveIPs": true,
      "blockTorExitNodes": true,
      "blockedIPs": ["192.168.1.100"]
    }
  }'
```

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

### Authenticate with Medama API (Login)

Source: https://context7.com/medama-io/medama/llms.txt

Log in to the Medama service using the Authentication API to obtain a session cookie. The session token is stored in an HTTP-only cookie named `_me_sess`.

```bash
# Login and receive session cookie
curl -X POST "http://localhost:8080/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "username": "admin",
    "password": "your_secure_password"
  }'

# Response: 200 OK with Set-Cookie header
# Cookie: _me_sess=<session_token>; Path=/; HttpOnly; SameSite=Lax; Secure
```

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

### User Settings API

Source: https://context7.com/medama-io/medama/llms.txt

Endpoints for updating user settings and deleting user accounts.

```APIDOC
## PATCH /user

### Description
Updates the settings for the current user. This includes changing username, password, and various privacy-related settings.

### Method
PATCH

### Endpoint
/user

### Parameters
#### Request Body
- **username** (string) - Optional - The new username for the user.
- **password** (string) - Optional - The new password for the user.
- **settings** (object) - Optional - An object containing user-specific settings.
  - **blockAbusiveIPs** (boolean) - Optional - Whether to block abusive IP addresses.
  - **blockTorExitNodes** (boolean) - Optional - Whether to block Tor exit nodes.
  - **blockedIPs** (array of strings) - Optional - A list of IP addresses to block.

### Request Example
```json
{
  "username": "newusername",
  "password": "new_secure_password",
  "settings": {
    "blockAbusiveIPs": true,
    "blockTorExitNodes": true,
    "blockedIPs": ["192.168.1.100"]
  }
}
```

### Response
#### Success Response (200)
Returns a success message upon successful update.

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

## DELETE /user

### Description
Deletes the current user's account.

### Method
DELETE

### Endpoint
/user

### Response
#### Success Response (200)
Returns a success message upon successful deletion.

#### Response Example
```json
{
  "message": "User account deleted successfully."
}
```
```

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

### POST /event/hit - Page View

Source: https://context7.com/medama-io/medama/llms.txt

Sends a page view event when a user loads a page. The tracker automatically sends this event with user context.

```APIDOC
## POST /event/hit - Page View

### Description
Sends a page view event when a user loads a page. The tracker automatically sends this event with user context.

### Method
POST

### Endpoint
`/event/hit`

### Request Body
- **e** (string) - Required - Event type. Should be "load" for page views.
- **b** (string) - Required - Beacon ID, unique per page view.
- **u** (string) - Required - Full page URL.
- **r** (string) - Optional - Referrer URL.
- **p** (boolean) - Optional - Indicates if the user is unique (true/false).
- **q** (boolean) - Optional - Indicates if this is the first visit to this specific page (true/false).
- **t** (string) - Optional - User timezone (e.g., "America/New_York").
- **d** (object) - Optional - Custom properties (e.g., {"author": "John Doe", "category": "Technology"}).

### Request Example
```bash
curl -X POST "http://localhost:8080/event/hit" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -d '{ 
    "e": "load",
    "b": "m5x7k9p2q",
    "u": "https://example.com/blog/post-1?utm_source=twitter",
    "r": "https://twitter.com/",
    "p": true,
    "q": true,
    "t": "America/New_York",
    "d": {
      "author": "John Doe",
      "category": "Technology"
    }
  }'
```

### Response
#### Success Response (204)
No Content.

#### Response Example
(No content)
```

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

### JavaScript History API Router

Source: https://github.com/medama-io/medama/blob/main/tracker/tests/fixtures/history/index.html

This JavaScript code implements a client-side router using the History API. It defines functions to navigate between different views by pushing new states to the history and updating the DOM. The router listens for 'popstate' events to handle browser navigation.

```javascript
function navigate(path) {
  history.pushState(null, "", path);
  router();
}

function router() {
  const content = document.getElementById("content");
  const path = window.location.pathname;

  switch (path) {
    case "/history/index.html":
      content.innerHTML = "<p>This is the home page.</p>";
      break;
    case "/history/about.html":
      content.innerHTML = "<p>This is the about page.</p>";
      break;
    case "/history/contact.html":
      content.innerHTML = "<p>This is the contact page.</p>";
      break;
  }
}

window.addEventListener("popstate", router);
router(); // Initial load
```

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

### Medama Tracker Script Variants

Source: https://context7.com/medama-io/medama/llms.txt

Utilize different Medama tracker script variants for specific tracking needs, including custom properties on page load and click events. Each variant maintains a minimal bundle size.

```html
<!-- Default tracker: Basic page views and time tracking (~0.75KB gzipped) -->
<script defer src="https://YOUR_DOMAIN/script.js"></script>

<!-- Page events tracker: Includes custom properties on page load (~0.87KB gzipped) -->
<script defer src="https://YOUR_DOMAIN/script.js"></script>
<!-- Usage: Add data attributes to elements -->
<div data-m:load="plan=premium; source=homepage">Content</div>

<!-- Click events tracker: Track click events with custom properties (~0.95KB gzipped) -->
<script defer src="https://YOUR_DOMAIN/script.js"></script>
<!-- Usage: Add data attributes to clickable elements -->
<button data-m:click="action=signup; location=header">Sign Up</button>
```

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

### Send Custom Event (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Sends a custom event to track specific user interactions. This event can include arbitrary key-value properties for detailed analysis. The beacon ID is optional but can link the custom event to a specific page view.

```bash
curl -X POST "http://localhost:8080/event/hit" \
  -H "Content-Type: application/json" \
  -d '{
    "e": "custom",
    "b": "m5x7k9p2q",
    "g": "example.com",
    "d": {
      "action": "button_click",
      "button_id": "signup-cta",
      "plan": "premium"
    }
  }'
```

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

### Statistics API - Device & Browser Stats

Source: https://context7.com/medama-io/medama/llms.txt

Access statistics related to visitor browsers, operating systems, and device types to understand user technology.

```APIDOC
## GET /website/{website_domain}/browsers

### Description
Get statistics for visitor browsers.

### Method
GET

### Endpoint
`/website/{website_domain}/browsers`

### Parameters
#### Path Parameters
- **website_domain** (string) - Required - The domain of the website to retrieve statistics for.

### Request Example
```bash
curl -X GET "http://localhost:8080/website/example.com/browsers" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **browser** (string) - The name of the browser.
- **visitors** (integer) - The number of visitors using this browser.
- **visitors_percentage** (float) - The percentage of total visitors using this browser.
- **bounce_percentage** (float) - The bounce rate for visitors using this browser.
- **duration** (integer) - The average session duration in milliseconds for visitors using this browser.

#### Response Example
```json
[
  {
    "browser": "Chrome",
    "visitors": 680,
    "visitors_percentage": 54.4,
    "bounce_percentage": 42.1,
    "duration": 95000
  },
  {
    "browser": "Safari",
    "visitors": 280,
    "visitors_percentage": 22.4,
    "bounce_percentage": 38.5,
    "duration": 105000
  }
]
```

## GET /website/{website_domain}/os

### Description
Get statistics for visitor operating systems.

### Method
GET

### Endpoint
`/website/{website_domain}/os`

### Parameters
#### Path Parameters
- **website_domain** (string) - Required - The domain of the website to retrieve statistics for.

### Request Example
```bash
curl -X GET "http://localhost:8080/website/example.com/os" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **os** (string) - The name of the operating system.
- **visitors** (integer) - The number of visitors using this OS.
- **visitors_percentage** (float) - The percentage of total visitors using this OS.
- **bounce_percentage** (float) - The bounce rate for visitors using this OS.
- **duration** (integer) - The average session duration in milliseconds for visitors using this OS.

#### Response Example
```json
[
  {
    "os": "Windows",
    "visitors": 750,
    "visitors_percentage": 60.0,
    "bounce_percentage": 41.0,
    "duration": 98000
  }
]
```

## GET /website/{website_domain}/devices

### Description
Get statistics for visitor device types (desktop, mobile, tablet).

### Method
GET

### Endpoint
`/website/{website_domain}/devices`

### Parameters
#### Path Parameters
- **website_domain** (string) - Required - The domain of the website to retrieve statistics for.

### Request Example
```bash
curl -X GET "http://localhost:8080/website/example.com/devices" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **device_type** (string) - The type of device (e.g., desktop, mobile, tablet).
- **visitors** (integer) - The number of visitors using this device type.
- **visitors_percentage** (float) - The percentage of total visitors using this device type.
- **bounce_percentage** (float) - The bounce rate for visitors using this device type.
- **duration** (integer) - The average session duration in milliseconds for visitors using this device type.

#### Response Example
```json
[
  {
    "device_type": "desktop",
    "visitors": 800,
    "visitors_percentage": 64.0,
    "bounce_percentage": 40.5,
    "duration": 102000
  }
]
```
```

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

### User Management API

Source: https://context7.com/medama-io/medama/llms.txt

Manage user account settings, including username, password, and analytics preferences.

```APIDOC
## GET /user

### Description
Retrieve the current user's information and settings.

### Method
GET

### Endpoint
`/user`

### Parameters
No parameters are required for this endpoint.

### Request Example
```bash
curl -X GET "http://localhost:8080/user" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **username** (string) - The username of the current user.
- **settings** (object) - User-specific analytics settings.
  - **language** (string) - The preferred language for the user interface.
  - **script_type** (array of strings) - The types of scripts enabled for analytics.
  - **blockAbusiveIPs** (boolean) - Whether to block abusive IP addresses.
  - **blockTorExitNodes** (boolean) - Whether to block Tor exit nodes.
  - **blockedIPs** (array of strings) - A list of manually blocked IP addresses.
- **dateCreated** (integer) - Timestamp when the user account was created (Unix epoch seconds).
- **dateUpdated** (integer) - Timestamp when the user account was last updated (Unix epoch seconds).

#### Response Example
```json
{
  "username": "admin",
  "settings": {
    "language": "en",
    "script_type": ["default"],
    "blockAbusiveIPs": true,
    "blockTorExitNodes": false,
    "blockedIPs": []
  },
  "dateCreated": 1704067200,
  "dateUpdated": 1704153600
}
```
```

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

### Send Page Unload Event (Bash)

Source: https://context7.com/medama-io/medama/llms.txt

Sends a page unload event to track the time spent on a page. This event requires the beacon ID from the corresponding load event and the duration in milliseconds. It's often sent using `navigator.sendBeacon` for reliability.

```bash
curl -X POST "http://localhost:8080/event/hit" \
  -H "Content-Type: application/json" \
  -d '{
    "e": "unload",
    "b": "m5x7k9p2q",
    "m": 45000
  }'
```