{"openapi":"3.1.0","info":{"title":"UpHeron API","version":"1.0.0","summary":"Uptime monitoring for scripts and AI agents. Reads are free; extra monitors are paid per location with the Machine Payments Protocol.","description":"MCP server: https://upheron.com/mcp. Authenticate with a workspace API token in the `X-API-Key` header. Reading monitors, results and incidents is free within the rate limits. Creating a monitor is free while your plan has a free slot; beyond that a monitor costs $0.01 per location per 30 days, or $0.10 per location for life (VAT included), paid from credit or with MPP (HTTP 402). Agents without an account can create a monitor by paying alone: the response returns an API key for a new pay-as-you-go workspace. Docs: https://upheron.com/docs","contact":{"name":"UpHeron","url":"https://upheron.com/docs"}},"servers":[{"url":"https://upheron.com/api/v1"}],"x-service-info":{"categories":["monitoring","uptime","developer-tools"],"docs":{"homepage":"https://upheron.com","apiReference":"https://upheron.com/docs/api","llms":"https://upheron.com/llms.txt"}},"security":[{"apiKey":[]},{"bearer":[]}],"tags":[{"name":"Account","description":"Plan slots, credit and invoice details."},{"name":"Monitors","description":"Create, read and manage monitors."},{"name":"Results","description":"Check results and incidents. Always free."},{"name":"Payments","description":"Credit top-ups and receipts."},{"name":"Vulnerabilities","description":"Pro plans: the software a website monitor's site runs, and the vulnerabilities and unsupported releases found in it. Changes need `vulnerability_alerts` on the monitor."}],"paths":{"/account":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Plan slots, credit and prices","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/account/billing":{"put":{"tags":["Account"],"operationId":"updateBillingDetails","summary":"Set invoice details (name, address, country, VAT number)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingDetails"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BillingDetails"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/account/credit":{"get":{"tags":["Account"],"operationId":"listCreditTransactions","summary":"Credit movements, newest first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreditTransaction"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/locations":{"get":{"tags":["Monitors"],"operationId":"listLocations","summary":"Monitoring locations you can choose","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors":{"get":{"tags":["Monitors"],"operationId":"listMonitors","summary":"Every monitor and its current status","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Monitor"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}},"post":{"tags":["Monitors"],"operationId":"createMonitor","summary":"Create a monitor (paid when no plan slot is free, or without an account)","description":"Free while the plan has a free monitor slot. Otherwise costs the per-location price for 30 days (`billing_period: monthly`) or ten times that for life (`lifetime`), taken from credit; if credit is short the response is 402 with an MPP challenge for the difference. Ask POST /monitors/quote first to see the price.\n\nWithout an API token the request is always paid (agent-plan limits: 60-second minimum interval, no group monitors). After payment the 201 response also contains `api_key` and `workspace`: a new pay-as-you-go workspace that owns the monitor. The key is shown once.","security":[{"apiKey":[]},{"bearer":[]},{}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Repeating a request with the same key within 24 hours returns the monitor the first request created, without charging again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorInput"}}}},"responses":{"200":{"description":"Replayed by Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"},"heartbeat_url":{"type":["string","null"]},"api_key":{"type":"string","description":"Only when created without an account. Shown once."},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}},"x-payment-info":{"offers":[{"method":"stripe","intent":"charge","amount":"50","currency":"usd","description":"One monitor location (card via a Stripe shared payment token; at least $0.50, the rest stays as credit)"}]}}},"/monitors/quote":{"post":{"tags":["Monitors"],"operationId":"quoteMonitor","summary":"Price a monitor without creating it","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Repeating a request with the same key within 24 hours returns the monitor the first request created, without charging again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}":{"get":{"tags":["Monitors"],"operationId":"getMonitor","summary":"A monitor with uptime, recent results, 90 daily bars, its whole history and incidents","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorDetail"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}},"patch":{"tags":["Monitors"],"operationId":"updateMonitor","summary":"Change a monitor (adding locations to a paid monitor is paid)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}},"x-payment-info":{"offers":[{"method":"stripe","intent":"charge","amount":"50","currency":"usd","description":"One extra monitor location (card via a Stripe shared payment token; at least $0.50, the rest stays as credit)"}]}},"delete":{"tags":["Monitors"],"operationId":"deleteMonitor","summary":"Delete a monitor (frees its plan slot; paid monitors are not refunded)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/quote":{"post":{"tags":["Monitors"],"operationId":"quoteMonitorUpdate","summary":"Price a monitor change without applying it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/renew":{"post":{"tags":["Monitors"],"operationId":"renewMonitor","summary":"Renew a monthly paid monitor for 30 more days","description":"Renewals happen automatically every hour from credit. Call this to renew early (the 30 days are added to the remaining time) or to resume a monitor that was paused for non-payment. Pays from credit, or answers 402 with an MPP challenge.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"No fields; send {} or nothing."}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}},"x-payment-info":{"offers":[{"method":"stripe","intent":"charge","amount":"50","currency":"usd","description":"One monitor location for 30 days (card via a Stripe shared payment token; at least $0.50, the rest stays as credit)"}]}}},"/monitors/{id}/renew/quote":{"post":{"tags":["Monitors"],"operationId":"quoteMonitorRenewal","summary":"Price a renewal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/vulnerabilities":{"get":{"tags":["Vulnerabilities"],"operationId":"getVulnerabilities","summary":"Findings in the website's software (exploited and most severe first) and the software they were matched on","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/vulnerabilities/scan":{"post":{"tags":["Vulnerabilities"],"operationId":"scanSoftware","summary":"Scan the website for its software and check it now instead of waiting for the weekly scan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued; `pending` is true until it ran","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/vulnerabilities/{finding_id}/fixed":{"post":{"tags":["Vulnerabilities"],"operationId":"markFixed","summary":"Record that a finding's software was upgraded: to version, or by default to the first version that fixes it; the monitor is checked again","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"finding_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","examples":["14.2.25"],"description":"The version installed; defaults to the finding's fix_version."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/software":{"post":{"tags":["Vulnerabilities"],"operationId":"addSoftware","summary":"Add software the website runs, by name (Debian, nginx), package (npm:lodash, wp-plugin:slug) or NVD product (cpe:vendor:product)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","examples":["Debian","nginx","npm:lodash","wp-plugin:woocommerce"]},"version":{"type":["string","null"],"examples":["12","1.24.0"]}}}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/software/import":{"post":{"tags":["Vulnerabilities"],"operationId":"importSoftware","summary":"Import a manifest, lockfile, Dockerfile, Compose file or a plain list (one \"name version\" per line); importing a filename again replaces what it added","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","maxLength":5000000,"description":"The file's text, or the list."},"filename":{"type":"string","examples":["package-lock.json","Dockerfile","composer.lock"],"description":"Tells the format; leave out for a plain list."},"name":{"type":"string","examples":["frontend/package.json"],"description":"Labels the import; importing under the same label again replaces it. Defaults to the filename, or \"software list\" for a list."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Vulnerabilities"},{"type":"object","properties":{"import":{"$ref":"#/components/schemas/SoftwareImport"}}}]}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}},"delete":{"tags":["Vulnerabilities"],"operationId":"removeSoftwareImport","summary":"Remove everything a file imported","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/software/{software_id}":{"patch":{"tags":["Vulnerabilities"],"operationId":"updateSoftware","summary":"Set an entry's version (it then counts as added by hand), or ignore or restore it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"software_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":["string","null"]},"ignored":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}},"delete":{"tags":["Vulnerabilities"],"operationId":"removeSoftware","summary":"Remove an entry; software the scan found is ignored instead, so it is not added back","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"software_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vulnerabilities"}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/software-catalog":{"get":{"tags":["Vulnerabilities"],"operationId":"listSoftwareCatalog","summary":"Software known by name; any package (npm:, composer:, pypi:, gem:, go:, maven:, nuget:, cargo:), wp-plugin:/wp-theme: slug or cpe:vendor:product works too","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"kind":{"enum":["os","software"]}}}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/alert-channels":{"get":{"tags":["Account"],"operationId":"listAlertChannels","summary":"Notification contacts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertChannel"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}},"post":{"tags":["Account"],"operationId":"createAlertChannel","summary":"Add a notification contact (email contacts must confirm a link first)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","kind","destination"],"properties":{"name":{"type":"string"},"kind":{"type":"string","examples":["email","webhook","slack"]},"destination":{"type":"string","description":"Email address or URL."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertChannel"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/alert-channels/{id}":{"delete":{"tags":["Account"],"operationId":"deleteAlertChannel","summary":"Remove a notification contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/alert-channels/{id}/test":{"post":{"tags":["Account"],"operationId":"testAlertChannel","summary":"Send a test alert","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/pause":{"post":{"tags":["Monitors"],"operationId":"pauseMonitor","summary":"Stop checking","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/resume":{"post":{"tags":["Monitors"],"operationId":"resumeMonitor","summary":"Start checking again","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/results":{"get":{"tags":["Results"],"operationId":"listResults","summary":"Recent check results, newest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Result"}}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/monitors/{id}/uptime":{"get":{"tags":["Results"],"operationId":"getUptimeHistory","summary":"Daily uptime for any range, kept for as long as the monitor","description":"One entry per UTC day, oldest first. Without `from` and `to`, every day from the first check (`since`) to today. At most 3660 days per request.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UptimeDay"}},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"since":{"type":["string","null"],"format":"date","description":"The first day with checks."}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}},"/incidents":{"get":{"tags":["Results"],"operationId":"listIncidents","summary":"Incidents, newest first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/incidents/{id}":{"get":{"tags":["Results"],"operationId":"getIncident","summary":"One incident with its events","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Incident"}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/incidents/{id}/acknowledge":{"post":{"tags":["Results"],"operationId":"acknowledgeIncident","summary":"Acknowledge an incident","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Incident"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/credits":{"post":{"tags":["Payments"],"operationId":"topUpCredit","summary":"Buy prepaid credit with MPP","description":"Always answered with 402 and an MPP challenge for `amount_cents` until paid. Cards (Stripe shared payment tokens) need at least $0.50.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents"],"properties":{"amount_cents":{"type":"integer","minimum":50,"maximum":100000}}}}}},"responses":{"200":{"description":"Paid; returns the account with its new credit","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"503":{"description":"Payments are switched off"}},"x-payment-info":{"offers":[{"method":"stripe","intent":"charge","amount":"50","currency":"usd","description":"Prepaid credit (card via a Stripe shared payment token; at least $0.50, the rest stays as credit)"}]}}},"/payments":{"get":{"tags":["Payments"],"operationId":"listPayments","summary":"Payments, newest first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}}}},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"}}}},"/payments/{id}":{"get":{"tags":["Payments"],"operationId":"getPayment","summary":"One payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Payment"}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}},"/payments/{id}/receipt":{"get":{"tags":["Payments"],"operationId":"getReceipt","summary":"Receipt with seller and VAT details (JSON, or Markdown with Accept: text/markdown)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"type":"object"}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Recommended. Works on every request, including paid retries that carry an MPP credential in Authorization. Takes a workspace API token (pgk_) or an access token an agent got through auth.md (pga_, see /auth.md)."},"bearer":{"type":"http","scheme":"bearer","description":"Alternative for requests without an MPP credential. Agents get bearer access tokens themselves through auth.md: start at /.well-known/oauth-authorization-server or /auth.md."}},"responses":{"401":{"description":"Missing, invalid, revoked or expired token. WWW-Authenticate carries resource_metadata, where an agent starts auth.md registration.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. Carries an MPP challenge in WWW-Authenticate: Payment.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"403":{"description":"The token lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; see Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object"}}},"PaymentRequired":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"error":{"const":"payment_required"},"amount_due":{"type":"string","examples":["0.02"]},"currency":{"const":"usd"},"quote":{"$ref":"#/components/schemas/Quote"},"help":{"type":"string"}}},"MonitorInput":{"type":"object","properties":{"name":{"type":"string","maxLength":160,"description":"Shown in alerts and on status pages."},"kind":{"type":"string","default":"http","enum":["http","api","ssl","domain","dns","blacklist","email_auth","malware","tcp","ssh","smtp","imap","pop","ftps","ping","ntp","udp","minecraft","transaction","micro_transaction","extended_transaction","group","cloud_status","page_speed","webhook","heartbeat","repository"],"description":"What to check. `heartbeat` and `webhook` wait for your calls instead of probing. `repository` reads a GitHub or GitLab repository's dependency manifests daily and alerts on vulnerabilities in them, on every plan; put the repository URL in `url` (optionally …/tree/branch/folder) and, for a private repository (Pro plan or a paid monitor), an access token in `check_options.token`."},"url":{"type":"string","description":"URL, or host[:port] for network checks."},"method":{"type":"string","enum":["GET","HEAD","POST","PUT","PATCH","DELETE"],"default":"GET"},"interval_seconds":{"type":"integer","minimum":10,"maximum":86400,"default":300,"description":"Seconds between checks. Paid monitors may use 10 or more on any plan; monitors in plan slots follow the plan (300 on Free, 10 on Pro)."},"timeout_ms":{"type":"integer","minimum":500,"maximum":60000,"default":10000},"locations":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Location codes from GET /locations. Defaults to the first location."},"expected_status_min":{"type":"integer","default":200},"expected_status_max":{"type":"integer","default":399},"keyword":{"type":"string","maxLength":2000,"description":"Text the response body must contain."},"request_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent with the check; stored encrypted and never returned."},"request_body":{"type":"string","maxLength":65536},"check_options":{"type":"object","description":"Kind-specific options, such as `json_path`/`expected_value` for `api`, `steps` for transactions, `warn_days` for ssl. Ports go in `url` as host:port. See /docs/api#check-options."},"failure_threshold":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Failed checks in a row before an incident opens. The default alerts on the first failed check."},"recovery_threshold":{"type":"integer","minimum":1,"maximum":10,"default":2},"confirmation_threshold":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Locations that must agree a check failed."},"heartbeat_grace_seconds":{"type":"integer","description":"For heartbeat and webhook monitors."},"expiry_alerts":{"type":"boolean","default":true,"description":"`http` and `api` monitors: check the domain registration and (for HTTPS) the TLS certificate daily. Domain alerts come 30, 14, 7, 3 and 1 days before expiry; certificate alerts only once automatic renewal should have happened (a sixth of the certificate's lifetime, at most 14 days). Uses no extra monitor."},"vulnerability_alerts":{"type":"boolean","default":false,"description":"Paid plans, `http` and `api` monitors: scan the website weekly for the software it runs and alert on newly published vulnerabilities in it (OSV.dev with the GitHub Advisory Database, NVD, new CVE records, CISA KEV, endoflife.date)."},"vulnerability_severity":{"type":"string","enum":["low","medium","high","critical"],"default":"low","description":"The lowest severity that alerts. Actively exploited vulnerabilities and releases reaching end of support always alert."},"charts":{"type":"string","enum":["both","uptime","response"],"default":"both","description":"Charts on public status pages: uptime bars (the last 90 days, or the whole history), the last 24 hours of response time, or both."},"alert_channel_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Notification contacts to alert. Defaults to all of the workspace's contacts."},"billing_period":{"type":"string","enum":["monthly","lifetime"],"default":"monthly","description":"Only for paid monitors (no free plan slot). `monthly` costs the per-location price every 30 days, renewed from credit; `lifetime` costs ten times that once and never renews."}},"required":["name"]},"Monitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":160,"description":"Shown in alerts and on status pages."},"kind":{"type":"string","default":"http","enum":["http","api","ssl","domain","dns","blacklist","email_auth","malware","tcp","ssh","smtp","imap","pop","ftps","ping","ntp","udp","minecraft","transaction","micro_transaction","extended_transaction","group","cloud_status","page_speed","webhook","heartbeat","repository"],"description":"What to check. `heartbeat` and `webhook` wait for your calls instead of probing. `repository` reads a GitHub or GitLab repository's dependency manifests daily and alerts on vulnerabilities in them, on every plan; put the repository URL in `url` (optionally …/tree/branch/folder) and, for a private repository (Pro plan or a paid monitor), an access token in `check_options.token`."},"url":{"type":"string","description":"URL, or host[:port] for network checks."},"method":{"type":"string","enum":["GET","HEAD","POST","PUT","PATCH","DELETE"],"default":"GET"},"interval_seconds":{"type":"integer","minimum":10,"maximum":86400,"default":300,"description":"Seconds between checks. Paid monitors may use 10 or more on any plan; monitors in plan slots follow the plan (300 on Free, 10 on Pro)."},"timeout_ms":{"type":"integer","minimum":500,"maximum":60000,"default":10000},"locations":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Location codes from GET /locations. Defaults to the first location."},"expected_status_min":{"type":"integer","default":200},"expected_status_max":{"type":"integer","default":399},"keyword":{"type":"string","maxLength":2000,"description":"Text the response body must contain."},"request_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent with the check; stored encrypted and never returned."},"request_body":{"type":"string","maxLength":65536},"check_options":{"type":"object","description":"Kind-specific options, such as `json_path`/`expected_value` for `api`, `steps` for transactions, `warn_days` for ssl. Ports go in `url` as host:port. See /docs/api#check-options."},"failure_threshold":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Failed checks in a row before an incident opens. The default alerts on the first failed check."},"recovery_threshold":{"type":"integer","minimum":1,"maximum":10,"default":2},"confirmation_threshold":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Locations that must agree a check failed."},"heartbeat_grace_seconds":{"type":"integer","description":"For heartbeat and webhook monitors."},"expiry_alerts":{"type":"boolean","default":true,"description":"`http` and `api` monitors: check the domain registration and (for HTTPS) the TLS certificate daily. Domain alerts come 30, 14, 7, 3 and 1 days before expiry; certificate alerts only once automatic renewal should have happened (a sixth of the certificate's lifetime, at most 14 days). Uses no extra monitor."},"vulnerability_alerts":{"type":"boolean","default":false,"description":"Paid plans, `http` and `api` monitors: scan the website weekly for the software it runs and alert on newly published vulnerabilities in it (OSV.dev with the GitHub Advisory Database, NVD, new CVE records, CISA KEV, endoflife.date)."},"vulnerability_severity":{"type":"string","enum":["low","medium","high","critical"],"default":"low","description":"The lowest severity that alerts. Actively exploited vulnerabilities and releases reaching end of support always alert."},"charts":{"type":"string","enum":["both","uptime","response"],"default":"both","description":"Charts on public status pages: uptime bars (the last 90 days, or the whole history), the last 24 hours of response time, or both."},"alert_channel_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Notification contacts to alert. Defaults to all of the workspace's contacts."},"billing_period":{"enum":["monthly","lifetime",null]},"status":{"enum":["enabled","paused"]},"current_status":{"enum":["pending","up","down","degraded"]},"consecutive_failures":{"type":"integer"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"next_check_at":{"type":["string","null"],"format":"date-time"},"billing":{"enum":["plan","paid"]},"paid_locations":{"type":"integer"},"paid_until":{"type":["string","null"],"format":"date-time","description":"End of the paid period for monthly paid monitors."},"billing_state":{"enum":["active","overdue"]}}},"MonitorDetail":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"},"uptime":{"type":"object","properties":{"day":{"type":["number","null"]},"week":{"type":["number","null"]},"month":{"type":["number","null"]},"average_latency_ms":{"type":["integer","null"]}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"days":{"type":"array","description":"The last 90 UTC days, oldest first, each with its failures (`problems`, kept 30 days on the free plan, 90 on paid plans).","items":{"type":"object"}},"all_time":{"type":"object","description":"The whole history in about 90 bars: days, then weeks from Monday, then months.","properties":{"unit":{"type":"string","enum":["day","week","month"]},"since":{"type":["string","null"],"format":"date"},"periods":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"checks":{"type":"integer"},"up":{"type":"integer"},"down":{"type":"integer"},"latency_ms":{"type":["integer","null"]}}}}}},"incident_totals":{"type":"object","description":"Incidents and the minutes they lasted: in all, and in the last 90 days (`recent`).","properties":{"all":{"type":"object","properties":{"count":{"type":"integer"},"minutes":{"type":"integer"}}},"recent":{"type":"object","properties":{"count":{"type":"integer"},"minutes":{"type":"integer"}}}}},"incidents":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}}},"UptimeDay":{"type":"object","properties":{"date":{"type":"string","format":"date"},"checks":{"type":"integer"},"up":{"type":"integer","description":"Successful checks."},"down":{"type":"integer","description":"Failed checks."},"restricted":{"type":"integer"},"latency_ms":{"type":["integer","null"],"description":"Average response time of the successful checks."}}},"Result":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["up","down","degraded"]},"status_code":{"type":["integer","null"]},"latency_ms":{"type":["integer","null"]},"location_code":{"type":"string"},"checked_at":{"type":"string","format":"date-time"},"error":{"type":["string","null"]},"details":{"type":"object"},"repeats":{"type":"integer","description":"How many checks this result stands for. The last two hours and a monitor's last 120 checks are always single checks; older checks with the same outcome are merged into one result per 15 minutes (within the last day) or per hour."},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When repeats > 1: the last of the merged checks."},"latency_max_ms":{"type":["integer","null"],"description":"When repeats > 1: the slowest of the merged checks; latency_ms is their mean."}}},"Incident":{"type":"object","properties":{"id":{"type":"string"},"monitor_id":{"type":"string"},"monitor_name":{"type":"string"},"status":{"enum":["open","acknowledged","resolved"]},"title":{"type":"string"},"cause":{"type":["string","null"]},"started_at":{"type":"string","format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"}}},"Vulnerabilities":{"type":"object","properties":{"available":{"type":"boolean","description":"The plan includes vulnerability alerts."},"supported":{"type":"boolean","description":"An http or api monitor."},"enabled":{"type":"boolean"},"severity":{"enum":["low","medium","high","critical"]},"scanned_at":{"type":["string","null"],"format":"date-time"},"scan_error":{"type":["string","null"]},"checked_at":{"type":["string","null"],"format":"date-time"},"pending":{"type":"boolean","description":"A scan or check is queued or running."},"software":{"type":"array","items":{"$ref":"#/components/schemas/Software"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}}}},"Software":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product":{"type":"string","examples":["wordpress","npm:lodash","wp-plugin:elementor"]},"name":{"type":"string"},"version":{"type":["string","null"]},"source":{"enum":["detected","import","manual"]},"evidence":{"type":["string","null"],"description":"Where the scan saw it, or the imported file's name."},"ignored":{"type":"boolean"}}},"Finding":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"vuln_id":{"type":"string","examples":["CVE-2024-4577","GHSA-f82v-jwr5-mffw","EOL:debian:11"]},"aliases":{"type":"array","items":{"type":"string"}},"kind":{"enum":["vulnerability","end_of_life"]},"product":{"type":"string"},"software_name":{"type":"string"},"version":{"type":["string","null"]},"version_known":{"type":"boolean","description":"False when the version is unknown and the advisory only may apply."},"summary":{"type":["string","null"]},"severity":{"enum":["low","medium","high","critical",null]},"score":{"type":["number","null"]},"fixed_in":{"type":["string","null"]},"fix_version":{"type":["string","null"],"description":"The first version that fixes it, for its version's release line; what marking it fixed records by default."},"marked_fixed_version":{"type":["string","null"],"description":"The version it was marked fixed with, while that version is still affected."},"url":{"type":["string","null"]},"source":{"enum":["osv","nvd","cve","endoflife"]},"published_at":{"type":["string","null"],"format":"date-time"},"exploited_on":{"type":["string","null"],"format":"date","description":"Added to CISA's Known Exploited Vulnerabilities catalog."},"alerted_at":{"type":["string","null"],"format":"date-time"}}},"SoftwareImport":{"type":"object","properties":{"file":{"type":"string"},"format":{"type":"string"},"imported":{"type":"integer"},"unrecognized":{"type":"array","items":{"type":"string"},"description":"Lines of a plain list that named nothing known."}}},"AlertChannel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"destination":{"type":"string"},"enabled":{"type":"boolean"},"confirmed":{"type":"boolean"}}},"Location":{"type":"object","properties":{"code":{"type":"string","examples":["fra-1"]},"name":{"type":"string"},"online":{"type":"boolean"}}},"Quote":{"type":"object","properties":{"billing":{"enum":["plan","paid","replay"]},"billing_period":{"enum":["monthly","lifetime",null]},"locations":{"type":"array","items":{"type":"string"}},"price_cents":{"type":"integer"},"credit_cents":{"type":"integer"},"amount_due_cents":{"type":"integer","description":"0 when a plan slot or credit covers it."}}},"Account":{"type":"object","properties":{"plan":{"type":"string"},"plan_monitors":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"free":{"type":"integer"}}},"paid_monitors":{"type":"integer"},"credit_cents":{"type":"integer"},"pricing":{"type":"object","properties":{"currency":{"const":"usd"},"price_per_location_cents":{"type":"integer","description":"Per location per 30 days."},"lifetime_price_per_location_cents":{"type":"integer"},"renewal_days":{"type":"integer"},"grace_days":{"type":"integer"},"minimum_top_up_cents":{"type":"integer"},"payments_enabled":{"type":"boolean"},"vat_included":{"type":"boolean"}}},"billing_details":{"$ref":"#/components/schemas/BillingDetails"}}},"BillingDetails":{"type":"object","properties":{"billing_name":{"type":["string","null"]},"billing_address":{"type":["string","null"]},"billing_country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2, decides the VAT treatment."},"billing_vat_id":{"type":["string","null"],"description":"EU VAT number with country prefix; enables the reverse charge for EU businesses outside Bulgaria."}}},"CreditTransaction":{"type":"object","properties":{"id":{"type":"string"},"amount_cents":{"type":"integer"},"balance_cents":{"type":"integer"},"reason":{"enum":["payment","monitor","renewal"]},"description":{"type":["string","null"]},"payment_id":{"type":["string","null"]},"monitor_id":{"type":["string","null"]},"inserted_at":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","properties":{"id":{"type":"string"},"method":{"enum":["stripe","tempo"]},"reference":{"type":"string"},"amount_cents":{"type":"integer"},"currency":{"const":"usd"},"purpose":{"type":"string"},"net_cents":{"type":"integer"},"vat_cents":{"type":"integer"},"vat_rate":{"type":"string"},"vat_treatment":{"type":"string"},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}