Project Settings File Structure Guide

The settings.json file contains all configuration and metadata for a Uplinkr project, including probe definitions, alert rules, and project status.

File Location

storage/app/private/uplinkr/<project-name>/settings.json

File Structure

{
    "project": "my-project",
    "label": "My Website Monitoring",
    "description": "Production website health monitoring",
    "created_at": "2026-01-25 18:01:06",
    "updated_at": "2026-01-26 04:32:41",
    "status": "enabled",
    "probes": [...],
    "alerts": [...]
}

Field Reference

Project Metadata

Field	Type	Description
project	string	Unique project identifier (used for directory naming)
label	string	Human-readable project name
description	string	Detailed project description
created_at	datetime	Project creation timestamp
updated_at	datetime	Last modification timestamp
status	string	Project status: enabled or disabled

Probes Array

The probes array contains all health check configurations for the project:

{
    "url": "https://example.com/api/health",
    "project": "my-project",
    "method": "GET",
    "headers": [
        "Authorization: Bearer token",
        "Content-Type: application/json"
    ],
    "body": null
}

Probe Fields

Field	Type	Description
url	string	Target URL to monitor
project	string	Project identifier (matches parent project)
method	string	HTTP method: GET, POST, PUT, DELETE, etc.
headers	array	Optional HTTP headers (array of strings)
body	string|null	Optional request body for POST/PUT requests

Legacy note: Older project files may still contain header; Uplinkr normalizes this to headers for compatibility.

Alerts Array

The alerts array defines alerting rules and notification channels:

{
    "enabled": true,
    "trigger_after_failures": 20,
    "cooldown_minutes": 120,
    "latency_threshold_ms": 1000,
    "trigger_after_slow": 10,
    "channels": [
        "mail",
        "webhook"
    ]
}

Alert Fields

Field	Type	Description
enabled	boolean	Whether alerts are active
trigger_after_failures	integer	Number of consecutive failures before alerting
cooldown_minutes	integer	Minutes to wait before re-alerting for the same issue
latency_threshold_ms	integer	Response time threshold in milliseconds
trigger_after_slow	integer	Number of consecutive slow responses before alerting
channels	array	Notification channels configured for this project (commonly mail, log, webhook).

Commands That Modify This File

uplinkr:project:init

Creates the initial settings.json file when initializing a new project.

Example:

php artisan uplinkr:project:init --project=my-project

Result:

• Creates project directory
• Generates settings.json with default values
• Sets project status to enabled

uplinkr:project:update

Updates project metadata such as label, description, or status.

Example:

php artisan uplinkr:project:update --project=my-project --label="New Label"

Modifies:

• label, description, status fields
• Updates updated_at timestamp

uplinkr:project:add:probe

Adds a new probe configuration to the probes array.

Example:

php artisan uplinkr:project:add:probe --project=my-project \
    --url=https://example.com/health \
    --method=GET

Modifies:

• Appends new probe to probes array
• Updates updated_at timestamp

uplinkr:project:alerts

Configures or updates alert rules in the alerts array.

Example:

php artisan uplinkr:project:alerts \
    --project=my-project \
    --failures=30 \
    --cooldown=60

Modifies:

• Updates alert configuration
• Adds or removes notification channels
• Updates updated_at timestamp

Example: Complete Project File

{
    "project": "uplinkr-dev-api-test",
    "label": "Uplinkr Dev API Test",
    "description": "Development environment API monitoring",
    "created_at": "2026-01-25 18:01:06",
    "updated_at": "2026-01-26 04:32:41",
    "status": "enabled",
    "probes": [
        {
            "url": "https://api.example.com/health",
            "project": "uplinkr-dev-api-test",
            "method": "GET",
            "headers": [],
            "body": null
        },
        {
            "url": "https://api.example.com/auth",
            "project": "uplinkr-dev-api-test",
            "method": "POST",
            "headers": [
                "Content-Type: application/json"
            ],
            "body": "{\"username\":\"test\",\"password\":\"test\"}"
        }
    ],
    "alerts": [
        {
            "enabled": true,
            "trigger_after_failures": 20,
            "cooldown_minutes": 120,
            "latency_threshold_ms": 1000,
            "trigger_after_slow": 10,
            "channels": [
                "mail",
                "webhook"
            ]
        }
    ]
}

Best Practices

Manual Editing

While you can manually edit settings.json, it’s recommended to use the provided Artisan commands to:

• Ensure proper validation
• Maintain consistent timestamps
• Avoid JSON syntax errors

Probe Organization

• Group related endpoints in the same project
• Use descriptive URLs that identify the service
• Include authentication headers when needed

Alert Configuration

• Set trigger_after_failures high enough to avoid false positives
• Use cooldown_minutes to prevent alert spam
• Configure appropriate latency_threshold_ms for your application

Backup

Since this file contains all project configuration:

• Include it in your backup strategy
• Version control it for infrastructure-as-code approaches
• Keep copies before major changes

Related Topics

• Storage Structure - Overall storage architecture
• Probe Data - Understanding probe execution results
• Alerts & State - How alert states are tracked
• Commands Reference - All available commands