REST API reference.
Manage sites, read incidents, trigger playbooks, and embed live trust badges — all via a JSON REST API authenticated with a Bearer token.
01 / Auth
Generate an API key
In the Liulum dashboard, go to Settings > API Keys and click Generate key. Give it a descriptive name (e.g. n8n integration) and select the scopes you need. Copy the key — it is shown only once.
02 / Auth
Authenticate requests
Pass your API key in the Authorization header as a Bearer token. All requests must use HTTPS. API keys are scoped to your account — never share them or commit them to source control.
curl https://liulum.com/api/v1/sites \
-H 'Authorization: Bearer lm_live_xxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json'03 / Auth
Handle rate limits
The API allows 120 requests per minute per API key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. When you hit the limit, the API returns 429 Too Many Requests. Implement exponential backoff on 429 responses.
# Rate limit response headers
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705315200API key scopes
Available permission scopes
sites:read
Read site status and health scores
incidents:read
Read incidents and history
playbooks:run
Trigger allow-listed playbooks
badges:read
Serve trust badge SVG
webhooks:manage
Create and delete webhook endpoints
Endpoints
Available endpoints
/api/v1/sitesList all sites in your portfolio.
[
{
"id": "proj_xxx",
"name": "My Store",
"url": "https://your-store.com",
"status": "healthy",
"health_score": 98,
"last_checked": "2025-01-15T10:24:00Z"
}
]/api/v1/sites/:idGet detailed status for a single site, including monitored paths and current health score.
/api/v1/sites/:id/incidentsList incidents for a site. Supports ?status=open|resolved and ?limit= pagination.
[
{
"id": "inc_xxx",
"site_id": "proj_xxx",
"severity": "high",
"title": "Checkout returned 500",
"path": "/checkout",
"status_code": 500,
"status": "open",
"started_at": "2025-01-15T10:23:00Z",
"resolved_at": null
}
]/api/v1/sites/:id/playbooks/:playbook_id/runTrigger an allowed playbook on a site. Returns the playbook run ID for status polling.
{
"run_id": "run_xxx",
"playbook": "cache-flush",
"status": "queued",
"queued_at": "2025-01-15T10:25:00Z"
}/api/v1/sites/:id/badge.svgReturns the live SVG trust badge for a site. Embed this URL directly in an img tag — it updates in real time.
Error codes
Standard error responses
401 UNAUTHORIZED
Missing or invalid API key.
403 FORBIDDEN
Valid key but insufficient scope for this endpoint.
404 NOT_FOUND
Site or incident ID does not exist or belongs to another account.
429 RATE_LIMITED
Exceeded 120 requests per minute. Retry after X-RateLimit-Reset.
500 INTERNAL_ERROR
Unexpected server error. Contact support with the request ID from the response body.
Build on top of Care.
Generate an API key from your Liulum Care dashboard and start integrating.