### Quick Start with create-zinalog

Source: https://zinalog.com/docs/getting-started

Scaffolds and runs a local ZinaLog instance. After running, open http://localhost:4000 to complete the initial setup.

```bash
npx create-zinalog my-logger  

cd my-logger  

npm run dev  

```

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

### Clone and Install ZinaLog

Source: https://zinalog.com/docs/getting-started

Clones the ZinaLog repository and installs dependencies for manual setup.

```bash
git clone https://github.com/zinalog/zinalog.git  

cd zinalog  

npm install  

```

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

### Create .env for Manual Setup

Source: https://zinalog.com/docs/getting-started

Creates a .env file in the project root with required environment variables for manual setup.

```bash
PORT=4000  

DATABASE_PATH=./data/logs.db  

ENCRYPTION_KEY=your-64-char-hex-key  # generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"  

```

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

### Docker Compose Setup for ZinaLog

Source: https://zinalog.com/docs/getting-started

Docker Compose configuration for ZinaLog with persistent storage and the command to start it. Access the dashboard at http://your-server-ip:4000.

```yaml
services:  

  zinalog:  

    image: ghcr.io/zinalog/zinalog:latest  

    container_name: zinalog  

    restart: unless-stopped  

    ports:  

      - "4000:4000"  

    environment:  

      PORT: "4000"  

      HOSTNAME: "0.0.0.0"  

      DATABASE_PATH: /data/logs.db  

      TRUST_PROXY: "false" # Set to "true" if behind Nginx/Traefik  

      # Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"  

      # Set ENCRYPTION_KEY in a .env file next to this compose file or in your shell.  

      ENCRYPTION_KEY: ${ENCRYPTION_KEY:-}  

    volumes:  

      - zinalog-data:/data  

  

volumes:  

  zinalog-data:  

```

```bash
docker compose up -d  

```

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

### GET /api/settings

Source: https://zinalog.com/docs/api-reference

Returns system settings. Requires admin permission.

```APIDOC
## GET /api/settings

### Description
Returns system settings.

### Method
GET

### Endpoint
/api/settings

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Response
#### Success Response (200)
- **retention_days** (integer) - Default `30`.
- **max_logs** (integer) - Default `100000`.
- **session_idle_timeout_minutes** (integer) - Default `30`.
- **announcements_enabled** (string) - `"1"` or `"0"`, default `"1"`.

#### Response Example
{
  "retention_days": 30,
  "max_logs": 100000,
  "session_idle_timeout_minutes": 30,
  "announcements_enabled": "1"
}
```

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

### Run ZinaLog Development Server

Source: https://zinalog.com/docs/getting-started

Starts the ZinaLog development server. Then open http://localhost:4000.

```bash
npm run dev  

```

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

### POST /api/logs Example Payload

Source: https://zinalog.com/docs/api-reference

Example JSON payload for POST /api/logs. Uses level, message, service, stack, and metadata fields. The stack string contains escaped newlines.

```json
{
  "level": "error",
  "message": "Critical failure in payment module",
  "service": "billing-v1",
  "stack": "Error: Connection failed\n    at Socket.onConnect (index.js:45)...",
  "metadata": {
    "attempt_count": 3,
    "env": "production",
    "region": "us-east-1"
  }
}
```

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

### GET /api/users

Source: https://zinalog.com/docs/api-reference

Lists users, available roles, and services. Requires operator permission.

```APIDOC
## GET /api/users

### Description
Lists users, available roles, and services.

### Method
GET

### Endpoint
/api/users

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `operator` role.

### Response
#### Success Response (200)
- Users (array) - The list of users.
- Roles (array) - The available roles.
- Services (array) - The available services.

#### Response Example
{
  "users": [],
  "roles": [],
  "services": []
}
```

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

### GET /api/keys

Source: https://zinalog.com/docs/api-reference

Lists masked API keys. Requires operator permission.

```APIDOC
## GET /api/keys

### Description
Lists masked API keys.

### Method
GET

### Endpoint
/api/keys

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `operator` role.

### Response
#### Success Response (200)
- API keys (array) - The list of masked API keys.

#### Response Example
{
  "keys": []
}
```

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

### GET /api/export

Source: https://zinalog.com/docs/api-reference

Exports logs in JSON or CSV format using the same filter fields as GET /api/logs. Use format=csv for CSV; JSON is the default.

```APIDOC
## GET /api/export

### Description
Exports logs in `json` or `csv` format using the same filter fields as `GET /api/logs`. Use `format=csv` for CSV; JSON is the default.

### Method
GET

### Endpoint
/api/export

### Parameters
#### Query Parameters
- **format** (string) - Optional - Export format: `csv` or `json` (default).
- **level** (string) - Optional - Filter by level (comma-separated: `error,warning`).
- **service** (string) - Optional - Filter by a specific service name.
- **search** (string) - Optional - Full-text search on message and service fields.
- **from** (string) - Optional - ISO date string for the start of the range.
- **to** (string) - Optional - ISO date string for the end of the range.
- **page** (integer) - Optional - Page number (Default: 1).
- **limit** (integer) - Optional - Logs per page (Default: 50, Max: 200).

### Response
#### Success Response (200)
Returns the exported logs in the requested format.

```

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

### GET /api/alerts

Source: https://zinalog.com/docs/api-reference

Returns sanitized alert and notification settings. Requires admin permission.

```APIDOC
## GET /api/alerts

### Description
Returns sanitized alert and notification settings.

### Method
GET

### Endpoint
/api/alerts

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Response
#### Success Response (200)
- Alert settings (object) - The sanitized alert and notification settings.

#### Response Example
{
  "alerts": {}
}
```

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

### GET /api/services

Source: https://zinalog.com/docs/api-reference

Returns the list of discovered service names for filtering and dashboard views.

```APIDOC
## GET /api/services

### Description
Returns the list of discovered service names for filtering and dashboard views.

### Method
GET

### Endpoint
/api/services

### Response
#### Success Response (200)
Returns a list of service names.

```

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

### Run Docusaurus with Algolia environment variables

Source: https://zinalog.com/docs/search

Sets the required Algolia environment variables for local development and starts the Docusaurus dev server. The variables are read from the environment before the site is built.

```bash
ALGOLIA_APP_ID=your_app_id \
ALGOLIA_INDEX_NAME=your_index_name \
ALGOLIA_SEARCH_API_KEY=your_public_search_key \
npm run start
```

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

### GET /api/monitors

Source: https://zinalog.com/docs/api-reference

Retrieves a list of monitors. This endpoint is used by the dashboard to display monitors.

```APIDOC
## GET /api/monitors

### Description
Retrieves a list of monitors.

### Method
GET

### Endpoint
/api/monitors

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Monitors (array) - The list of monitors.

#### Response Example
{
  "monitors": []
}
```

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

### GET /api/stats

Source: https://zinalog.com/docs/api-reference

Returns summary data for the overview charts, including log counts by level and service distribution.

```APIDOC
## GET /api/stats

### Description
Returns summary data for the overview charts (log counts by level, service distribution, etc.).

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
Returns summary statistics for the overview charts.

```

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

### GET /api/announcements

Source: https://zinalog.com/docs/api-reference

Returns announcements applicable to the current version and user. Requires viewer permission.

```APIDOC
## GET /api/announcements

### Description
Returns announcements that apply to this ZinaLog version and have not been dismissed by the current user.

### Method
GET

### Endpoint
/api/announcements

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `viewer` role.

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether announcements are enabled.
- **announcements** (array) - The list of announcements.

#### Response Example
{
  "enabled": true,
  "announcements": []
}
```

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

### GET /api/monitors/recent-checks

Source: https://zinalog.com/docs/api-reference

Returns recent checks across monitors. Requires viewer role.

```APIDOC
## GET /api/monitors/recent-checks

### Description
Returns recent checks across monitors. `limit` defaults to 20 and is capped at 100.

### Method
GET

### Endpoint
/api/monitors/recent-checks

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Number of recent checks to return. Default: 20, max: 100.

### Response
#### Success Response (200)
Returns recent checks across monitors.
```

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

### GET /api/services

Source: https://zinalog.com/docs/api-reference

Retrieves a list of services. This endpoint is used by the dashboard to display available services.

```APIDOC
## GET /api/services

### Description
Retrieves a list of services.

### Method
GET

### Endpoint
/api/services

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Services (array) - The list of services.

#### Response Example
{
  "services": []
}
```

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

### GET /api/logs

Source: https://zinalog.com/docs/api-reference

Retrieves log entries from ZinaLog. This endpoint is used by the dashboard to display logs.

```APIDOC
## GET /api/logs

### Description
Retrieves log entries from ZinaLog.

### Method
GET

### Endpoint
/api/logs

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Log entries (array) - The requested log data.

#### Response Example
{
  "logs": []
}
```

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

### GET /api/monitors

Source: https://zinalog.com/docs/api-reference

Returns all monitors with sensitive fields masked. Viewer routes can read monitor state.

```APIDOC
## GET /api/monitors

### Description
Returns all monitors with sensitive fields masked.

### Method
GET

### Endpoint
/api/monitors

### Response
#### Success Response (200)
Returns an array of monitor objects with sensitive fields masked.
```

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

### GET /api/issues

Source: https://zinalog.com/docs/api-reference

Retrieves a list of issues. This endpoint is used by the dashboard to display issues.

```APIDOC
## GET /api/issues

### Description
Retrieves a list of issues.

### Method
GET

### Endpoint
/api/issues

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Issues (array) - The list of issues.

#### Response Example
{
  "issues": []
}
```

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

### GET /api/export

Source: https://zinalog.com/docs/api-reference

Exports log data. This endpoint is used by the dashboard to download logs.

```APIDOC
## GET /api/export

### Description
Exports log data.

### Method
GET

### Endpoint
/api/export

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Exported log data.

#### Response Example
{
  "export": "data"
}
```

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

### GET /api/monitors/:id

Source: https://zinalog.com/docs/api-reference

Returns a monitor, up to the 50 retained recent checks, and uptime statistics for the last 24 hours, 7 days, 30 days, and 365 days.

```APIDOC
## GET /api/monitors/:id

### Description
Returns a monitor, up to the 50 retained recent checks, and uptime statistics for the last 24 hours, 7 days, 30 days, and 365 days (`stats24h`, `stats7d`, `stats30d`, and `stats365d`).

### Method
GET

### Endpoint
/api/monitors/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The monitor ID.

### Response
#### Success Response (200)
Returns a monitor object with recent checks and uptime statistics. For HTTPS monitors, the monitor object can include `ssl_expires_at`, `ssl_issuer`, and `ssl_valid` from the most recent check. HTTP monitors can also include `domain_expires_at`, `domain_registrar`, and `domain_checked_at`; domain data is refreshed daily for active hostname targets when WHOIS data is available.
```

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

### GET /api/access-audit

Source: https://zinalog.com/docs/api-reference

Returns whether auditing is enabled, the retention window, and the 200 most recent records. Requires admin permission.

```APIDOC
## GET /api/access-audit

### Description
Returns whether auditing is enabled, the retention window, and the 200 most recent records.

### Method
GET

### Endpoint
/api/access-audit

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether auditing is enabled.
- **retention_days** (integer) - The retention window in days.
- **records** (array) - The 200 most recent audit records.

#### Response Example
{
  "enabled": true,
  "retention_days": 30,
  "records": []
}
```

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

### GET /api/stats

Source: https://zinalog.com/docs/api-reference

Retrieves statistics about logs and system usage. This endpoint is used by the dashboard to display metrics.

```APIDOC
## GET /api/stats

### Description
Retrieves statistics about logs and system usage.

### Method
GET

### Endpoint
/api/stats

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Statistics (object) - The requested statistics.

#### Response Example
{
  "stats": {}
}
```

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

### GET /api/monitors/:id/checks

Source: https://zinalog.com/docs/api-reference

Returns the retained check history and uptime stats for a monitor. ZinaLog retains the 50 most recent raw checks per monitor.

```APIDOC
## GET /api/monitors/:id/checks

### Description
Returns the retained check history and uptime stats for a monitor. ZinaLog retains the 50 most recent raw checks per monitor; longer-range uptime is available from the monitor-detail endpoint.

### Method
GET

### Endpoint
/api/monitors/:id/checks

### Parameters
#### Path Parameters
- **id** (string) - Required - The monitor ID.

#### Query Parameters
- **limit** (number) - Optional - Number of retained checks to return. Default: 200, max: 2000 (at most 50 are retained).
- **hours** (number) - Optional - Stats lookback window. Default: 24, max: 720.

### Response
#### Success Response (200)
Returns the retained check history and uptime stats.
```

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

### GET /api/issues

Source: https://zinalog.com/docs/api-reference

Lists issues for a given log level, most recently seen first, up to 100. Requires viewer role.

```APIDOC
## GET /api/issues

### Description
Lists issues for one log level, most recently seen first (up to 100). Requires `viewer`.

### Method
GET

### Endpoint
/api/issues

### Parameters
#### Query Parameters
- **level** (string) - Optional - `debug`, `info`, `warning`, or `error`. Default: `error`.
- **status** (string) - Optional - `open`, `resolved`, `ignored`, or `all`. Default: `open`.

### Response
#### Success Response (200)
Returns `{ "issues": [...], "counts": { "open": 0, "resolved": 0, "ignored": 0 } }`, where `counts` covers every status for the level. Each issue includes `id`, `fingerprint`, `level`, `service`, `title` (the latest message), `status`, `count`, `first_seen`, `last_seen`, `status_changed_at`, and `status_changed_by`.

#### Response Example
{
  "issues": [],
  "counts": {
    "open": 0,
    "resolved": 0,
    "ignored": 0
  }
}
```

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

### GET /api/monitors/:id

Source: https://zinalog.com/docs/api-reference

Retrieves a specific monitor by ID. This endpoint is used by the dashboard to display monitor details.

```APIDOC
## GET /api/monitors/:id

### Description
Retrieves a specific monitor by ID.

### Method
GET

### Endpoint
/api/monitors/:id

### Path Parameters
- **id** (string) - Required - The ID of the monitor.

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Monitor details (object) - The requested monitor.

#### Response Example
{
  "monitor": {}
}
```

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

### GET /api/stream

Source: https://zinalog.com/docs/api-reference

Streams log data in real-time. This endpoint is used by the dashboard for live log viewing.

```APIDOC
## GET /api/stream

### Description
Streams log data in real-time.

### Method
GET

### Endpoint
/api/stream

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Stream of log entries.

#### Response Example
{
  "logs": []
}
```

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

### GET /api/logs

Source: https://zinalog.com/docs/api-reference

Query and filter historical logs. Supports filtering by level, service, full-text search, date range, and pagination.

```APIDOC
## GET /api/logs

### Description
Query and filter historical logs.

### Method
GET

### Endpoint
/api/logs

### Parameters
#### Query Parameters
- **level** (string) - Optional - Filter by level (comma-separated: `error,warning`).
- **service** (string) - Optional - Filter by a specific service name.
- **search** (string) - Optional - Full-text search on message and service fields.
- **from** (string) - Optional - ISO date string for the start of the range.
- **to** (string) - Optional - ISO date string for the end of the range.
- **page** (integer) - Optional - Page number (Default: 1).
- **limit** (integer) - Optional - Logs per page (Default: 50, Max: 200).

### Response
#### Success Response (200)
Returns the filtered logs.

```

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

### GET /api/errors

Source: https://zinalog.com/docs/api-reference

Retrieves error-related data. This endpoint is used by the dashboard to display error information.

```APIDOC
## GET /api/errors

### Description
Retrieves error-related data.

### Method
GET

### Endpoint
/api/errors

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Error data (object) - The requested error information.

#### Response Example
{
  "errors": []
}
```

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

### GET /api/errors

Source: https://zinalog.com/docs/api-reference

Returns error-level logs grouped by fingerprint, up to 100 groups ordered by count. Each group includes fingerprint, most recent message, service, level, count, first_seen, last_seen, and latest_id.

```APIDOC
## GET /api/errors

### Description
Returns error-level logs grouped by fingerprint, up to 100 groups ordered by count.

### Method
GET

### Endpoint
/api/errors

### Response
#### Success Response (200)
Returns an array of error groups. Each group includes:
- **fingerprint** (string) - The fingerprint of the error group.
- **message** (string) - The most recent message.
- **service** (string) - The service name.
- **level** (string) - The log level.
- **count** (integer) - The number of occurrences.
- **first_seen** (string) - Timestamp of the first occurrence.
- **last_seen** (string) - Timestamp of the last occurrence.
- **latest_id** (string) - The ID of the latest log entry.

```

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

### GET /api/issues/:id

Source: https://zinalog.com/docs/api-reference

Retrieves a specific issue by ID. This endpoint is used by the dashboard to display issue details.

```APIDOC
## GET /api/issues/:id

### Description
Retrieves a specific issue by ID.

### Method
GET

### Endpoint
/api/issues/:id

### Path Parameters
- **id** (string) - Required - The ID of the issue.

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Issue details (object) - The requested issue.

#### Response Example
{
  "issue": {}
}
```

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

### GET /api/issues/:id

Source: https://zinalog.com/docs/api-reference

Returns a single issue with hourly occurrence counts for the last 7 days and the 20 most recent matching logs. Requires viewer role.

```APIDOC
## GET /api/issues/:id

### Description
Returns `{ issue, hourly, samples }`: the issue, hourly occurrence counts for the last 7 days (`[{ "hour", "count" }]`, oldest first), and the 20 most recent matching logs. Requires `viewer`.

### Method
GET

### Endpoint
/api/issues/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The issue ID.

### Response
#### Success Response (200)
Returns an object with `issue`, `hourly`, and `samples` fields.

#### Response Example
{
  "issue": {},
  "hourly": [
    {
      "hour": "",
      "count": 0
    }
  ],
  "samples": []
}
```

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

### GET /api/monitors/recent-checks

Source: https://zinalog.com/docs/api-reference

Retrieves recent check results across all monitors. This endpoint is used by the dashboard to display recent monitor activity.

```APIDOC
## GET /api/monitors/recent-checks

### Description
Retrieves recent check results across all monitors.

### Method
GET

### Endpoint
/api/monitors/recent-checks

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Recent checks (array) - The list of recent check results.

#### Response Example
{
  "checks": []
}
```

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

### GET /api/stream

Source: https://zinalog.com/docs/api-reference

Server-Sent Events stream of new logs, used by the Live Stream page. Each event's data is a JSON array containing the new log entry, and a heartbeat comment is sent every 15 seconds.

```APIDOC
## GET /api/stream

### Description
Server-Sent Events stream of new logs, used by the Live Stream page. Each event's `data` is a JSON array containing the new log entry, and a `: heartbeat` comment is sent every 15 seconds to keep the connection open. Users restricted to specific services only receive logs for those services.

### Method
GET

### Endpoint
/api/stream

### Response
#### Success Response (200)
Server-Sent Events stream. Each event's data is a JSON array containing the new log entry.

```

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

### GET /api/monitors/:id/checks

Source: https://zinalog.com/docs/api-reference

Retrieves check results for a specific monitor. This endpoint is used by the dashboard to display monitor check history.

```APIDOC
## GET /api/monitors/:id/checks

### Description
Retrieves check results for a specific monitor.

### Method
GET

### Endpoint
/api/monitors/:id/checks

### Path Parameters
- **id** (string) - Required - The ID of the monitor.

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Checks (array) - The list of check results.

#### Response Example
{
  "checks": []
}
```

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

### Build and Run ZinaLog for Production

Source: https://zinalog.com/docs/getting-started

Builds and runs ZinaLog for production. Then open http://localhost:4000.

```bash
npm run build  

npm start  

```

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

### Run ZinaLog migration CLI in Docker

Source: https://zinalog.com/docs/getting-started

Run the migration CLI inside a Docker container. The image includes the CLI; subcommands are status, up, down, drop, and restore.

```bash
docker exec zinalog node scripts/zina-migrate.mjs status
```

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

### POST /api/settings

Source: https://zinalog.com/docs/api-reference

Updates system settings. Requires admin permission.

```APIDOC
## POST /api/settings

### Description
Updates system settings.

### Method
POST

### Endpoint
/api/settings

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Request Body
- **retention_days** (integer) - Optional - Number of days to retain logs.
- **max_logs** (integer) - Optional - Maximum number of logs.
- **session_idle_timeout_minutes** (integer) - Optional - Session idle timeout in minutes.
- **announcements_enabled** (string) - Optional - Must be `"0"` or `"1"`.

### Response
#### Success Response (200)
- Updated settings (object) - The updated settings.

#### Response Example
{
  "settings": {}
}
```

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

### ZinaLog migration CLI commands

Source: https://zinalog.com/docs/getting-started

Manual migration CLI commands for ZinaLog. Use these to inspect, apply, roll back, or restore database migrations. The drop command is destructive, and restore requires a backup filename.

```bash
npm run zina:migrate:status              # show applied and pending migrations  

npm run zina:migrate                     # apply pending migrations  

npm run zina:migrate:down -- 1           # roll back the last migration (or N steps)  

npm run zina:migrate:drop                # roll back every applied migration (destructive)  

npm run zina:make-migration -- add_thing # scaffold a new migration file  

npm run zina:migrate:restore             # list available backups  

npm run zina:migrate:restore -- <backup-filename>  

```

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

### POST /api/keys

Source: https://zinalog.com/docs/api-reference

Creates an API key. Requires operator permission.

```APIDOC
## POST /api/keys

### Description
Creates an API key.

### Method
POST

### Endpoint
/api/keys

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `operator` role.

### Request Body
- **name** (string) - Required - The name of the API key.
- **service** (string) - Optional - The service associated with the key.
- **allowed_ips** (array) - Optional - List of allowed IP addresses.
- **rate_limit** (integer) - Optional - Rate limit per minute, default `1000`.
- **expires_at** (string) - Optional - Expiration timestamp.

### Response
#### Success Response (200)
- Created API key (object) - The newly created API key.

#### Response Example
{
  "key": {}
}
```

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

### POST /api/monitors

Source: https://zinalog.com/docs/api-reference

Creates a monitor. Requires operator role or higher.

```APIDOC
## POST /api/monitors

### Description
Creates a monitor. Requires `operator` role or higher.

### Method
POST

### Endpoint
/api/monitors

### Parameters
#### Request Body
- **name** (string) - Required - Monitor name, 1-100 characters.
- **type** (string) - Required - One of `http`, `tcp`, or `ping`.
- **target** (string) - Required - HTTP URL for `http`, or a bare hostname/IP for `tcp` and `ping`.
- **port** (number) - Optional - TCP port, `1-65535`. (TCP only)
- **method** (string) - Optional - HTTP method. Defaults to `GET`.
- **headers** (object) - Optional - HTTP header name/value pairs. Values must be strings.
- **basic_auth_user** (string) - Optional - HTTP basic auth username.
- **basic_auth_pass** (string) - Optional - HTTP basic auth password.
- **expected_status** (string) - Optional - HTTP status list/ranges such as `200-299` or `200,301,302`. Defaults to `200-299`.
- **interval_seconds** (number) - Optional - Check interval, `10-86400`. Defaults to `60`.
- **timeout_seconds** (number) - Optional - Timeout, `1-120`, and less than `interval_seconds`. Defaults to `10`.
- **retries** (number) - Optional - Retry count, `0-10`. Defaults to `0`.
- **follow_redirects** (boolean) - Optional - HTTP redirect handling. Defaults to `true`.
- **verify_ssl** (boolean) - Optional - Verify TLS certificates for HTTPS checks. Defaults to `true`.
- **is_active** (boolean) - Optional - Whether the scheduler should run this monitor. Defaults to `true`.
- **notify_enabled** (boolean) - Optional - Whether this monitor should trigger notifications. Defaults to `true`.

### Request Example
{
  "name": "Example Monitor",
  "type": "http",
  "target": "https://example.com",
  "method": "GET",
  "interval_seconds": 60
}

### Response
#### Success Response (200)
Returns the created monitor object.
```

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

### Send a test log with curl

Source: https://zinalog.com/docs/getting-started

Send a test log entry to the ZinaLog API endpoint. Replace YOUR_API_KEY with your actual API key. After sending, the log appears instantly in the Live Stream on the dashboard Overview and is grouped into an issue under Logs > Errors.

```bash
curl -X POST http://localhost:4000/api/logs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "error",
    "message": "Payment gateway timed out",
    "service": "checkout-api",
    "metadata": {
      "transaction_id": "tx_12345",
      "latency_ms": 5000
    }
  }'
```

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

### POST /api/monitors/:id/test

Source: https://zinalog.com/docs/api-reference

Runs a monitor immediately and records the result. Requires operator role or higher.

```APIDOC
## POST /api/monitors/:id/test

### Description
Runs a monitor immediately and records the result. The response includes the new and previous monitor statuses plus the check result. HTTP checks protected by a Cloudflare Managed Challenge are reported with a `blocked` status rather than `down`.

### Method
POST

### Endpoint
/api/monitors/:id/test

### Parameters
#### Path Parameters
- **id** (string) - Required - The monitor ID.

### Response
#### Success Response (200)
Returns the new and previous monitor statuses plus the check result.
```

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

### zinalog-node Constructor

Source: https://zinalog.com/docs/sdk-libraries

Constructor options for the ZinaLog Node.js SDK.

```APIDOC
## Constructor

### Description
Creates a new ZinaLog Node.js SDK instance.

### Parameters
- `apiKey` (string) - Required - Your Zinalog API key
- `endpoint` (string) - Required - Base URL of your Zinalog instance (e.g. `https://logs.example.com`)
- `service` (string) - Optional - Service name attached to every log
- `batchSize` (number) - Optional - Flush when queue reaches this size (default: `50`)
- `flushIntervalMs` (number) - Optional - How often the queue is flushed in ms (default: `100`)
```

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

### flush()

Source: https://zinalog.com/docs/sdk-libraries

Manual flush method to ensure queued logs are sent before process exit.

```APIDOC
## flush()

### Description
Manually flushes the log queue. Logs are batched and flushed automatically, but calling `flush()` explicitly before process exit avoids dropping queued logs.

### Example
```js
process.on("SIGTERM", async () => {
  await log.flush();
  process.exit(0);
});
```
```

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

### POST /api/monitors/:id/duplicate

Source: https://zinalog.com/docs/api-reference

Creates a paused copy of an existing monitor. Requires operator role or higher.

```APIDOC
## POST /api/monitors/:id/duplicate

### Description
Creates a paused copy of an existing monitor. HTTP duplicates use an inert URL fragment to keep the target unique; TCP and ping duplicates receive a `-copy` target suffix that should be reviewed before activation.

### Method
POST

### Endpoint
/api/monitors/:id/duplicate

### Parameters
#### Path Parameters
- **id** (string) - Required - The monitor ID.

### Response
#### Success Response (200)
Returns the duplicated monitor object.
```

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

### POST /api/monitors

Source: https://zinalog.com/docs/api-reference

Creates a new monitor. This endpoint is used by the dashboard to add monitors.

```APIDOC
## POST /api/monitors

### Description
Creates a new monitor.

### Method
POST

### Endpoint
/api/monitors

### Authentication
- Bearer Token
- Session Cookie

### Request Body
- Monitor configuration (object) - Required - The monitor settings.

### Response
#### Success Response (200)
- Created monitor (object) - The newly created monitor.

#### Response Example
{
  "monitor": {}
}
```

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

### POST /api/users

Source: https://zinalog.com/docs/api-reference

Creates a user and emails a temporary password. Requires admin permission.

```APIDOC
## POST /api/users

### Description
Creates a user and emails a temporary password.

### Method
POST

### Endpoint
/api/users

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Request Body
- **username** (string) - Required - The username.
- **email** (string) - Required - The email address.
- **role** (string) - Required - One of `admin`, `operator`, or `viewer`.
- **mfa_enabled** (boolean) - Optional - Default `false`.
- **allowed_services** (array) - Optional - List of allowed services.

### Response
#### Success Response (200)
- Created user (object) - The newly created user.

#### Response Example
{
  "user": {}
}
```

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

### Generate ENCRYPTION_KEY with Node.js one-liner

Source: https://zinalog.com/docs/configuration

Generates a valid 32-byte (64-character) hex encryption key for the ENCRYPTION_KEY environment variable. Keep the output safe; losing it prevents decryption of previously encrypted settings.

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

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

### POST /api/alerts

Source: https://zinalog.com/docs/api-reference

Saves alert policy and notification channel settings. Requires admin permission.

```APIDOC
## POST /api/alerts

### Description
Saves alert policy and notification channel settings.

### Method
POST

### Endpoint
/api/alerts

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Request Body
- Alert policy and notification channel settings (object) - Required - The settings to save.

### Response
#### Success Response (200)
- Confirmation of save.

#### Response Example
{
  "status": "success"
}
```

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

### Log Methods

Source: https://zinalog.com/docs/sdk-libraries

Log methods for sending log messages at different levels. Each method accepts an optional second argument `{ metadata, stack }`.

```APIDOC
## log.info(msg, opts?)

### Description
Sends a log message at the `info` level.

### Parameters
- `msg` (string) - Required - The log message
- `opts` (object) - Optional - An object with optional `metadata` and `stack` fields
```

```APIDOC
## log.warn(msg, opts?)

### Description
Sends a log message at the `warning` level.

### Parameters
- `msg` (string) - Required - The log message
- `opts` (object) - Optional - An object with optional `metadata` and `stack` fields
```

```APIDOC
## log.error(msg, opts?)

### Description
Sends a log message at the `error` level.

### Parameters
- `msg` (string) - Required - The log message
- `opts` (object) - Optional - An object with optional `metadata` and `stack` fields
```

```APIDOC
## log.debug(msg, opts?)

### Description
Sends a log message at the `debug` level.

### Parameters
- `msg` (string) - Required - The log message
- `opts` (object) - Optional - An object with optional `metadata` and `stack` fields
```

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

### POST /api/alerts/test

Source: https://zinalog.com/docs/api-reference

Sends a test notification. Requires admin permission.

```APIDOC
## POST /api/alerts/test

### Description
Sends a test notification.

### Method
POST

### Endpoint
/api/alerts/test

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Response
#### Success Response (200)
- Confirmation of test notification.

#### Response Example
{
  "status": "success"
}
```

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

### DELETE /api/settings?days=30

Source: https://zinalog.com/docs/api-reference

Deletes logs older than the provided day count. Requires admin permission.

```APIDOC
## DELETE /api/settings?days=30

### Description
Deletes logs older than the provided day count.

### Method
DELETE

### Endpoint
/api/settings?days=30

### Query Parameters
- **days** (integer) - Required - The number of days; logs older than this will be deleted.

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Response
#### Success Response (200)
- Confirmation of deletion.

#### Response Example
{
  "status": "success"
}
```

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

### Bearer Token Authentication for /api/logs

Source: https://zinalog.com/docs/api-reference

Send this header with every POST request to /api/logs. The API key must be included in the Authorization header as a Bearer token.

```http
Authorization: Bearer <your_api_key>
```

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

### Set ENCRYPTION_KEY for Docker

Source: https://zinalog.com/docs/getting-started

Sets the ENCRYPTION_KEY environment variable in a .env file next to docker-compose.yml to encrypt SMTP credentials, webhook URLs, and monitor authentication secrets at rest.

```bash
ENCRYPTION_KEY=your-64-char-hex-key  

```

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

### POST /api/announcements/dismiss

Source: https://zinalog.com/docs/api-reference

Dismisses an announcement for the current user. Requires viewer permission.

```APIDOC
## POST /api/announcements/dismiss

### Description
Dismisses an announcement for the current user.

### Method
POST

### Endpoint
/api/announcements/dismiss

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `viewer` role.

### Request Body
- **id** (string) - Required - The announcement ID, 1-200 characters.

### Response
#### Success Response (200)
- Confirmation of dismissal.

#### Response Example
{
  "status": "success"
}

#### Error Response (400)
- Returned if the announcement is marked non-dismissible.
```

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

### POST /api/logs

Source: https://zinalog.com/docs/api-reference

Ingests log entries into ZinaLog. This endpoint is used to send log data for processing and storage.

```APIDOC
## POST /api/logs

### Description
Ingests log entries into ZinaLog.

### Method
POST

### Endpoint
/api/logs

### Authentication
- Bearer Token
- Session Cookie

### Request Body
- Log entries (object/array) - Required - The log data to ingest.

### Response
#### Success Response (200)
- Confirmation of ingestion.

#### Response Example
{
  "status": "success"
}
```

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

### POST /api/logs

Source: https://zinalog.com/docs/api-reference

The primary endpoint for sending logs to ZinaLog. Requires a bearer token in the Authorization header. Accepts a JSON payload with log details and returns a success or error response.

```APIDOC
## POST /api/logs

### Description
The primary endpoint for sending logs to ZinaLog. Requires a bearer token in the Authorization header. Accepts a JSON payload with log details and returns a success or error response.

### Method
POST

### Endpoint
/api/logs

### Authentication
Bearer Token: Authorization: Bearer <your_api_key>

### Parameters
#### Request Body
- **message** (string) - Required - The main log message.
- **level** (string) - Optional - One of: `debug`, `info`, `warning`, `error`. (Default: `info`)
- **service** (string) - Optional - Identifier for the sending service.
- **stack** (string) - Optional - A full stack trace or detailed error context.
- **metadata** (object) - Optional - Any arbitrary JSON object (e.g., `user_id`, `request_id`, `metrics`).
- **fingerprint** (string) - Optional - Custom grouping key, up to 200 characters. Logs with the same `fingerprint`, level, and service are grouped into the same issue. When omitted, ZinaLog computes one from the message and stack trace.

### Size Limits
- **message** - Maximum 32,000 bytes
- **stack** - Maximum 64,000 bytes
- **metadata** (serialized JSON) - Maximum 64,000 bytes
- **service** - Maximum 200 bytes
- Requests whose `Content-Length` exceeds roughly 168 KB are rejected before parsing.

### Request Example
{
  "level": "error",
  "message": "Critical failure in payment module",
  "service": "billing-v1",
  "stack": "Error: Connection failed\n    at Socket.onConnect (index.js:45)...",
  "metadata": {
    "attempt_count": 3,
    "env": "production",
    "region": "us-east-1"
  }
}

### Response
#### Success Response (200)
- **status** (string) - Always "logged" on success.

#### Response Example
{
  "status": "logged"
}

#### Error Responses
- **400 Bad Request**: Invalid JSON, invalid log level, missing required fields, or a field exceeding its size limit.
- **401 Unauthorized**: Missing, invalid, revoked, or expired API key.
- **403 Forbidden**: API key IP restrictions block the request.
- **413 Payload Too Large**: The request body exceeds the maximum allowed size.
- **429 Too Many Requests**: The API key has reached its rate limit.
```

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

### Manual flush on SIGTERM with zinalog-node

Source: https://zinalog.com/docs/sdk-libraries

Flushes the log queue explicitly before process exit to avoid dropping queued logs. Use this in a SIGTERM handler to ensure all logs are sent when the process is terminated.

```javascript
process.on("SIGTERM", async () => {  

  await log.flush();  

  process.exit(0);  

});  
```

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

### POST /api/monitors/:id/duplicate

Source: https://zinalog.com/docs/api-reference

Duplicates a specific monitor. This endpoint is used by the dashboard to create a copy of a monitor.

```APIDOC
## POST /api/monitors/:id/duplicate

### Description
Duplicates a specific monitor.

### Method
POST

### Endpoint
/api/monitors/:id/duplicate

### Path Parameters
- **id** (string) - Required - The ID of the monitor.

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Duplicated monitor (object) - The new monitor.

#### Response Example
{
  "monitor": {}
}
```

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

### PATCH /api/access-audit

Source: https://zinalog.com/docs/api-reference

Updates auditing settings. Requires admin permission.

```APIDOC
## PATCH /api/access-audit

### Description
Updates auditing settings.

### Method
PATCH

### Endpoint
/api/access-audit

### Authentication
- Bearer Token
- Session Cookie

### Permissions
- Requires `admin` role.

### Request Body
- **enabled** (boolean) - Optional - Whether auditing is enabled.
- **retention_days** (integer) - Optional - Positive integer; saving this immediately deletes older records.

### Response
#### Success Response (200)
- Updated audit settings (object) - The updated settings.

#### Response Example
{
  "enabled": true,
  "retention_days": 30
}
```

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

### DELETE /api/monitors/:id

Source: https://zinalog.com/docs/api-reference

Deletes a monitor. Requires operator role or higher.

```APIDOC
## DELETE /api/monitors/:id

### Description
Deletes a monitor. Requires `operator` role or higher.

### Method
DELETE

### Endpoint
/api/monitors/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The monitor ID.

### Response
#### Success Response (200)
Returns a success indication.
```

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

### POST /api/monitors/:id/test

Source: https://zinalog.com/docs/api-reference

Triggers a test check for a specific monitor. This endpoint is used by the dashboard to validate monitor configuration.

```APIDOC
## POST /api/monitors/:id/test

### Description
Triggers a test check for a specific monitor.

### Method
POST

### Endpoint
/api/monitors/:id/test

### Path Parameters
- **id** (string) - Required - The ID of the monitor.

### Authentication
- Bearer Token
- Session Cookie

### Response
#### Success Response (200)
- Test result (object) - The result of the test check.

#### Response Example
{
  "result": {}
}
```