# Upwarden Agent Setup Guide

> Use this document when a user wants a coding agent to set up Upwarden for an existing application.

## Purpose

Upwarden is an uptime monitoring and status page platform. This guide is for coding agents that need to inspect a user's application, propose a monitoring plan, wait for approval, and then configure Upwarden through the REST API.

## Core Rule

Do not create resources immediately. Inspect the user's application, ask questions, propose a plan, wait for approval, then execute.

## Production Details

- Website: https://upwarden.eu
- Agent tutorial: https://upwarden.eu/agents
- API docs: https://upwarden.eu/docs
- OpenAPI 3.1 spec: https://upwarden.eu/api/v1/openapi/json
- API base URL: https://upwarden.eu/api/v1
- Auth: `Authorization: Bearer upw_your_api_key`
- API keys are created manually by the user at Dashboard -> Settings -> API Keys.

## Agent Workflow

1. Explore the codebase read-only.
2. Identify deployable services and reliability surfaces.
3. Detect existing health checks and background jobs.
4. Ask only questions that cannot be inferred from code.
5. Present setup options.
6. Wait for approval.
7. Create resources through the REST API.
8. Modify app code only if approved.
9. Verify with API calls and local tests.
10. Summarize the result.

## One-Prompt Setup Template

```text
You are setting up Upwarden for this application.

First read:
https://upwarden.eu/llms.txt

API key:
<UPWARDEN_API_KEY>

Your job:
1. Inspect this codebase before making changes.
2. Identify the application type, production entrypoints, existing health checks, background jobs, APIs, queues, cron jobs, and deployment setup.
3. Do not create anything yet.
4. Ask me concise questions for anything that cannot be inferred safely.
5. Propose a monitoring and status-page setup plan with options.
6. Wait for my approval.
7. After approval, use the Upwarden REST API to create the agreed setup.
8. If needed, add or adjust health endpoints or heartbeat pings in this codebase.
9. Run the project's relevant tests/checks.
10. Return the status page URL, monitor list, heartbeat URLs, and any code changes made.

Default to safe, minimal monitoring. Do not expose the API key in files, commits, logs, or screenshots.
```

## Agent Pseudocode

```text
read("https://upwarden.eu/llms.txt")

apiKey = ask_user_or_read_secret("UPWARDEN_API_KEY")
assert apiKey starts with "upw_"

repo = inspect_codebase_read_only()
app = infer_application_shape(repo)

candidates = {
  healthEndpoints: find_health_endpoints(repo),
  publicServices: find_public_routes_or_apps(repo),
  backgroundJobs: find_cron_jobs_queues_workers(repo),
  websocketEndpoints: find_websocket_servers(repo),
  deployTargets: find_deployment_config(repo)
}

questions = build_questions_for_missing_high_impact_info(candidates)
if questions not empty:
  ask_user(questions)

plan = propose_upwarden_setup(candidates, user_answers)
show_plan(plan)

wait_for_user_approval()

validate_api_key()
existing = list_existing_upwarden_resources()

resources = create_or_reuse_resources(plan, existing)

if plan.requires_code_changes:
  implement_health_or_heartbeat_changes()
  run_project_tests()

verify_created_resources(resources)

return_summary(resources)
```

## Discovery Checklist

Inspect the repository before asking the user:

- Framework and runtime
- Public production domain
- Existing health endpoints such as `/health`, `/api/health`, `/ready`, or `/live`
- Public web app entrypoints
- Public API entrypoints
- Background jobs, cron jobs, queue workers, scheduled functions
- WebSocket servers or realtime endpoints
- Databases, caches, mail servers, or TCP services that are externally monitorable
- DNS and domain ownership clues
- Deployment platform and environment variable conventions
- Existing test commands and lint/typecheck commands

## Questions To Ask Only If Missing

Ask concise questions only for decisions that cannot be inferred safely:

- Which production domain should Upwarden monitor?
- Should the status page be public?
- Which services should customers see as status page components?
- Do you want heartbeat monitoring for background jobs?
- Should I add a `/health` endpoint if none exists?
- Which check interval should I use within your plan limits?
- Should Upwarden monitor only customer-facing services, or also internal dependencies?

## Decision Tree

### If no health endpoint exists

Offer options:

- Option A: monitor an existing root or API endpoint.
- Option B, recommended: add a lightweight `/health` or `/api/health` endpoint and monitor that.
- Option C: create an external HTTP monitor now and leave code unchanged.

Wait for user approval before adding code.

### If background jobs exist

Recommend heartbeat monitoring:

- Create one heartbeat monitor per important job.
- Store the push URL in an environment variable or secret manager.
- Ping the push URL only after a successful job run.
- Do not commit heartbeat URLs to source control.

### If multiple services exist

Propose status page components such as:

- Web App
- API
- Worker
- Realtime / WebSocket
- Ingestion
- Billing / Webhooks
- Database or cache, only if externally monitorable

### If the user does not want a public status page

Create monitors only. Skip status page and component creation.

### If targets are local or private

Do not send localhost, private IPs, or internal hostnames to Upwarden. Ask the user for a publicly reachable production URL.

## Safe Defaults

- HTTP monitor interval: `60` seconds
- HTTP method: `GET`
- Expected status code: `200`
- Timeout: `10000` ms
- Status page: public
- Status page theme: `default`
- Status page slug: derive from app name unless the user provides one
- Health endpoint: prefer `/health` or `/api/health`
- Heartbeat grace period: match the job schedule plus a safe buffer

Plan limits may clamp intervals. If the API returns a different accepted interval, report it.

## API Execution Plan

Use the REST API only after the user approves the plan.

### 1. Validate the API key

```bash
curl -sS https://upwarden.eu/api/v1/monitors \
  -H "Authorization: Bearer $UPWARDEN_API_KEY"
```

### 2. List existing resources

```bash
curl -sS https://upwarden.eu/api/v1/status-pages \
  -H "Authorization: Bearer $UPWARDEN_API_KEY"

curl -sS https://upwarden.eu/api/v1/monitors \
  -H "Authorization: Bearer $UPWARDEN_API_KEY"
```

Reuse matching resources when names and targets clearly match the approved plan. Otherwise create missing resources.

### 3. Create a status page

```bash
curl -sS -X POST https://upwarden.eu/api/v1/status-pages \
  -H "Authorization: Bearer $UPWARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Status",
    "slug": "acme",
    "isPublic": true,
    "theme": "default",
    "enableSubscriptions": false,
    "daysShown": 90
  }'
```

### 4. Create an HTTP monitor

```bash
curl -sS -X POST https://upwarden.eu/api/v1/monitors \
  -H "Authorization: Bearer $UPWARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Health",
    "type": "http",
    "target": "https://api.example.com/health",
    "intervalSeconds": 60,
    "timeoutMs": 10000,
    "httpMethod": "GET",
    "expectedStatusCode": 200
  }'
```

### 5. Create a status page component linked to a monitor

```bash
curl -sS -X POST https://upwarden.eu/api/v1/status-pages/$STATUS_PAGE_ID/components \
  -H "Authorization: Bearer $UPWARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API",
    "description": "Public API health",
    "monitorId": "'$MONITOR_ID'"
  }'
```

### 6. Create a heartbeat monitor

```bash
curl -sS -X POST https://upwarden.eu/api/v1/monitors \
  -H "Authorization: Bearer $UPWARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup Job",
    "type": "heartbeat",
    "target": "daily-backup",
    "intervalSeconds": 86400,
    "gracePeriodSeconds": 3600
  }'
```

The response contains a `pushToken`. Ping it after a successful job run:

```bash
curl -sS https://upwarden.eu/api/v1/heartbeat/$PUSH_TOKEN
```

## Monitor Types

| Type | Use Case | Example Target |
|------|----------|----------------|
| HTTP | Web endpoints, APIs, health checks | `https://api.example.com/health` |
| TCP | Databases, caches, mail servers | `db.example.com:5432` |
| Ping | Server reachability | `server.example.com` |
| WebSocket | WS endpoints | `wss://ws.example.com` |
| DNS | DNS record resolution | `example.com` |
| Domain | Domain expiry tracking | `example.com` |
| Heartbeat | Cron jobs, background workers | Push-based job pings Upwarden |

## Safety Rules

- Do not create resources before approval.
- Do not expose the API key in files, commits, logs, screenshots, or test output.
- Do not use browser automation after API key creation unless the user explicitly asks.
- Do not monitor localhost, private IPs, or internal-only hostnames.
- Do not invent production URLs.
- Do not add health endpoints or heartbeat code without approval.
- Do not make destructive code changes to the user's application.
- Prefer the application's existing framework and conventions.
- Run the project's relevant checks after code changes.
- Return a concise summary with resource IDs, URLs, and any follow-up actions.

## What To Return To The User

After execution, summarize:

- Status page URL
- Created or reused monitors
- Created status page components
- Heartbeat push URLs or the environment variable names where they were stored
- Code changes made
- Tests/checks run
- Any assumptions or skipped items

## Webhook Reference

Outbound webhook events, payload schemas, and HMAC-SHA256 signature verification:
https://upwarden.eu/docs-webhooks

## Integrations

- Slack
- Discord
- Telegram
- Webhooks
- Opsgenie
- PagerDuty
- Pushover
- Twilio

## Contact

- Email: support@upwarden.eu
- Feature requests: https://userpulse.link/b/upwarden