Status for agents

curl https://status.acme.com/status.agent.json

{
  "schema": "upbutler.agent-status/v1",
  "verdict": "proceed",
  "status": "operational",
  "reason": "All systems operational",
  "retryAfterSec": null,
  "eta": null,
  "components": [],
  "incident": null,
  "page": "https://status.acme.com",
  "updatedAt": "2026-10-09T11:42:07.000Z"
}

{
  "schema": "upbutler.agent-status/v1",
  "verdict": "fallback",
  "status": "major_outage",
  "reason": "Card payments are failing",
  "retryAfterSec": 60,
  "eta": "2026-10-09T12:40:00.000Z",
  "etaSource": "history",
  "components": [
    { "key": "payments-api", "status": "major_outage", "verdict": "fallback", "hint": "Use the EU endpoint." },
    { "key": "dashboard", "status": "degraded", "verdict": "proceed" }
  ],
  "incident": {
    "id": "inc_1k4h5i0bqr4gb8nbezp",
    "url": "https://status.acme.com/incidents/inc_1k4h5i0bqr4gb8nbezp",
    "startedAt": "2026-10-09T12:04:11.000Z"
  },
  "page": "https://status.acme.com",
  "updatedAt": "2026-10-09T12:15:30.000Z"
}

curl "https://status.acme.com/status.agent.json?component=payments-api"
# HEAD is enough when you only need the word:
curl -sI https://status.acme.com/status.agent.json | grep -i x-status-verdict
# x-status-verdict: fallback

curl -X PATCH https://upbutler.com/api/v1/pages/acme \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "agentPolicy": {
        "default": { "degraded": "retry" },
        "components": {
          "checkout":     { "verdicts": { "major_outage": "fallback", "partial_outage": "fallback" }, "guidance": "Use the EU endpoint." },
          "batch-export": { "verdicts": { "major_outage": "pause" }, "guidance": "Queue exports; they run when we are back." }
        }
      }
    }
  }'

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Link: <https://status.acme.com/status.agent.json?component=payments-api>; rel="status"

const STATUS = '<https://status.acme.com/status.agent.json>; rel="status"';

// After your routes: every error response says where the status is.
app.use((err, req, res, next) => {
  res.set('Link', STATUS).status(err.status ?? 500).json({ error: err.message });
});

const STATUS = '<https://status.acme.com/status.agent.json>; rel="status"';

app.use(async (c, next) => {
  await next();
  if (c.res.status === 429 || c.res.status >= 500) c.res.headers.append('Link', STATUS);
});
app.onError((err, c) => c.json({ error: err.message }, 500, { Link: STATUS }));

// middleware.ts: add the header to every API response (it is small and harmless on a 200).
import { NextResponse } from 'next/server';

export function middleware() {
  const res = NextResponse.next();
  res.headers.append('Link', '<https://status.acme.com/status.agent.json>; rel="status"');
  return res;
}
export const config = { matcher: '/api/:path*' };

const STATUS = '<https://status.acme.com/status.agent.json>; rel="status"';

Bun.serve({
  async fetch(req) {
    const res = await handle(req).catch(() => new Response('Internal error', { status: 500 }));
    if (res.status === 429 || res.status >= 500) res.headers.append('Link', STATUS);
    return res;
  },
});

STATUS = '<https://status.acme.com/status.agent.json>; rel="status"'

@app.middleware("http")
async def status_link(request, call_next):
    try:
        response = await call_next(request)
    except Exception:
        return JSONResponse({"error": "internal"}, status_code=500, headers={"Link": STATUS})
    if response.status_code == 429 or response.status_code >= 500:
        response.headers.append("Link", STATUS)
    return response

# "always" makes nginx add the header to error responses too, including the ones it
# generates itself (502, 504) when your app is the thing that is down.
location /api/ {
    add_header Link '<https://status.acme.com/status.agent.json>; rel="status"' always;
    proxy_pass http://app;
}

# Optional, on your API host: one hop from a hostname to the verdict.
location = /.well-known/status {
    return 302 https://status.acme.com/status.agent.json;
}

claude mcp add --transport http acme-status https://status.acme.com/mcp

{
  "mcpServers": {
    "acme-status": { "type": "http", "url": "https://status.acme.com/mcp" }
  }
}

import { checkStatus, retryDelayMs, statusUrlFromResponse } from '@upbutler/sdk';

async function charge(body: unknown, attempt = 0): Promise<Response> {
  const res = await fetch('https://api.acme.com/v1/charges', { method: 'POST', body: JSON.stringify(body) });
  if (res.status !== 429 && res.status < 500) return res;

  // The failed response says where the status is. Fall back to the page you know.
  const s = await checkStatus(statusUrlFromResponse(res) ?? 'https://status.acme.com', { component: 'payments-api' });
  switch (s.verdict) {
    case 'fallback':
      return chargeWithBackupProvider(body);
    case 'pause':
      throw new PausedUntil(s.eta ?? new Date(Date.now() + s.retryAfterMs));
    default: // retry, or proceed (the page has not noticed yet): back off and try again
      if (attempt >= 4) throw new Error(`payments-api: ${s.reason}`);
      await new Promise((r) => setTimeout(r, retryDelayMs(s, attempt) || 1000 * 2 ** attempt));
      return charge(body, attempt + 1);
  }
}

import { shouldProceed } from '@upbutler/sdk';

// Before starting a long job that needs the service:
if (!(await shouldProceed('https://status.acme.com', { component: 'payments-api' }))) return;

from upbutler import check_status, retry_delay, should_proceed, status_url_from_headers

s = check_status("https://status.acme.com", component="payments-api")
if s["verdict"] == "fallback":
    use_backup_provider()
elif s["verdict"] == "pause":
    sleep_until(s["eta"] or time.time() + s["retryAfterSec"])
elif s["verdict"] == "retry":
    time.sleep(retry_delay(s, attempt))

# From a failed response (requests / httpx):
url = status_url_from_headers(response.headers, str(response.url))

# As a gate:
if not should_proceed("https://status.acme.com"):
    return

upbutler verdict https://status.acme.com -c payments-api
# fallback: Card payments are failing
#   check again in 60s, expected back 2026-10-09T12:40:00.000Z
#   payments-api: major_outage → fallback (Use the EU endpoint.)
#   https://status.acme.com/incidents/inc_1k4h5i0bqr4gb8nbezp

# The exit code is the verdict: 0 proceed, 10 retry, 11 fallback, 12 pause.
upbutler verdict https://status.acme.com && ./run-batch.sh