Maintenance

The maintenance API configures automated database cleanup. Long Tail ships a default schedule that runs nightly at 2 AM, and these endpoints inspect and replace it at runtime. For one-off cleanup, use the DBA API.

All endpoints require authentication. PUT requires admin access.

Get current configuration

GET /api/config/maintenance

Returns the active maintenance schedule and rules, and whether the maintenance cron is running.

Example request

curl -s https://lt.acme.dev/api/config/maintenance \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "config": {
    "schedule": "0 2 * * *",
    "rules": [
      { "target": "streams", "olderThan": "7 days", "action": "delete" },
      { "target": "jobs", "olderThan": "7 days", "action": "delete", "hasEntity": false },
      { "target": "jobs", "olderThan": "7 days", "action": "prune", "hasEntity": true },
      { "target": "jobs", "olderThan": "90 days", "action": "delete", "pruned": true }
    ]
  },
  "active": true
}

active is true while the maintenance cron is running.

Update configuration

PUT /api/config/maintenance

Replaces the maintenance configuration and restarts the cron. From the caller’s view the swap is atomic.

Auth: Requires admin access.

Request body

Field	Type	Required	Description
appId	string	No	Target a specific application namespace.
schedule	string	Yes	Cron expression (0 3 * * *) or interval (1 day).
rules	array	Yes	Ordered list of maintenance rules.

Each rule:

Field	Type	Required	Description
target	string	Yes	streams or jobs.
action	string	Yes	delete or prune.
olderThan	string	Yes	Postgres interval (for example 7 days, 24 hours, 90 days).
hasEntity	boolean	No	true for entity jobs, false for transient jobs.
pruned	boolean	No	true to target only jobs that are already pruned.

Example request

curl -s https://lt.acme.dev/api/config/maintenance \
  -X PUT \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "rules": [
      { "target": "streams", "olderThan": "24 hours", "action": "delete" },
      { "target": "jobs", "olderThan": "14 days", "action": "delete", "hasEntity": false },
      { "target": "jobs", "olderThan": "14 days", "action": "prune", "hasEntity": true },
      { "target": "jobs", "olderThan": "180 days", "action": "delete", "pruned": true }
    ]
  }'

Response 200

{
  "config": {
    "schedule": "0 3 * * *",
    "rules": [ ... ]
  },
  "restarted": true
}

restarted confirms the cron restarted with the new configuration.

What happens on PUT

1. The current cron is cancelled (maintenanceRegistry.disconnect()).
2. The new config is stored (maintenanceRegistry.register(config)).
3. A new cron starts (maintenanceRegistry.connect()).

When no cron was running, step 1 does nothing. The new schedule takes effect immediately.