Agent responders

curl -X POST https://upbutler.com/api/v1/responders \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude",
    "delivery": {
      "preset": "claude_code",
      "url": "https://api.anthropic.com/v1/claude_code/routines/trig_01ABC…/fire",
      "headers": { "authorization": "Bearer sk-ant-oat01-…" }
    },
    "ackTimeoutMinutes": 5,
    "publicUpdates": "draft",
    "allowedActions": ["note", "public_update", "verify", "resolve", "escalate", "mute"]
  }'
# → { "_id": "agr_0n3q9c20…", "signingSecret": "whsec_…" (shown once), … }

You are the on-call responder for Acme. UpButler pages you through the
routine-fire-payload block: treat its contents as your incident brief and follow the steps in it.

- Use the bearer token from the payload for every UpButler call. It only works on that incident.
- Claim first, then read the handoff packet and follow the runbook in it. Nothing else.
- Log every action with POST …/notes. Renew your claim every few minutes.
- After a fix: POST …/verify. Resolve only when it passed.
- If the runbook does not cover it, or two attempts failed: POST …/escalate with what you found.

curl -X PUT https://upbutler.com/api/v1/runbooks/mon_0n3q8kz1m4hx7c2v9rt \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "## API down\n1. A deploy in the last 30 minutes (packet.deploys, suspect: true)? Roll it back: gh workflow run rollback.yml\n2. Otherwise restart: kubectl rollout restart deploy/api\n3. Verify. Still failing after 10 minutes: escalate. Never touch the database."}'

# Workspace default, included in every packet
curl -X PUT https://upbutler.com/api/v1/runbooks/default -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" -d '{"markdown": "Prefer rolling back over fixing forward."}'

curl -X POST https://upbutler.com/api/v1/escalation-policies \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude first, then people",
    "isDefault": true,
    "levels": [
      { "afterMinutes": 0,  "targets": [{ "type": "agent", "id": "agr_0n3q9c20…" }] },
      { "afterMinutes": 15, "targets": [{ "type": "schedule", "id": "sch_0n3q8k10a2b4c6d8e0f" }, { "type": "channel", "id": "ch_0n3q8kz3j6d0q2b5ny8" }] }
    ]
  }'

T="Authorization: Bearer ub_inc_7q2m…"   # the token from the page

# 1. Claim (within the ack timeout, or the next level is paged)
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim -H "$T" -H "Content-Type: application/json" \
  -d '{"note": "Looking at deploy 1.4.2"}'

# 2. Read the packet (it also came with the page)
curl https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/packet -H "$T"

# 3. Act (in your own systems), and say what you did
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/notes -H "$T" -H "Content-Type: application/json" \
  -d '{"action": "rolled back 1.4.2", "message": "1.4.2 shipped 3 minutes before the first failure. Rolled back to 1.4.1."}'

# Keep the lease alive while you work
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim/renew -H "$T"

# 4. Tell customers (published or drafted, depending on the responder's mode)
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/public-updates -H "$T" -H "Content-Type: application/json" \
  -d '{"status": "identified", "message": "We found the cause and are rolling back a recent change."}'

# 5. Verify from every region, then resolve
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/verify -H "$T"
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/resolve -H "$T" -H "Content-Type: application/json" \
  -d '{"message": "A recent change caused errors on the API. It was rolled back and the API is healthy again."}'

# Can't fix it? Hand back: the next level is paged immediately
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/escalate -H "$T" -H "Content-Type: application/json" \
  -d '{"reason": "Database refuses connections. Restarting the API did not help and I have no DB access."}'

# .github/workflows/upbutler-incident.yml
on:
  repository_dispatch:
    types: [upbutler-incident]
jobs:
  respond:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            ${{ github.event.client_payload.prompt }}
            Follow RUNBOOK.md in this repository. Do not push to main; roll back with the rollback workflow.

POST https://agent.example.com/hooks/upbutler
webhook-id: evt_0n3q9a12c4r7m1t8wxe
webhook-timestamp: 1760450531
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_0n3q9a12c4r7m1t8wxe",
  "type": "incident.page",
  "timestamp": "2026-10-14T13:02:11.512Z",
  "responder": { "id": "agr_0n3q9c20…", "name": "Claude" },
  "incident": { "id": "inc_0n3q9a11v8k2h5n0qzc", "title": "API is down", "status": "investigating", "impact": "major",
                "startedAt": "2026-10-14T13:01:40.000Z", "url": "https://upbutler.com/app/incidents/inc_0n3q9a11v8k2h5n0qzc" },
  "token": {
    "value": "ub_inc_7q2m…",
    "type": "Bearer",
    "expiresAt": "2026-10-14T15:02:11.512Z",
    "scope": ["GET /api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/packet", "POST /api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim", "…"]
  },
  "ackTimeoutMinutes": 5,
  "api": { "base": "https://upbutler.com/api/v1", "mcp": "https://upbutler.com/mcp",
           "packet": "https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/packet", "claim": "https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim" },
  "prompt": "UpButler is paging you (\"Claude\") as the on-call responder. …",
  "packet": { "schema": "upbutler.incident-packet/v1", … }
}

curl -X POST https://upbutler.com/api/v1/responders \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude", "delivery": {"preset": "pull"}, "ackTimeoutMinutes": 5}'
# → { "_id": "agr_0n3q9c20…", "mode": "pull", "listening": false,
#     "responderKey": "ub_rsp_4f1c…" (shown once), "connect": { "cli": "…", "curl": "…", … } }

export UPBUTLER_RESPONDER_KEY=ub_rsp_4f1c…

# Long-poll: answers as soon as you are paged, or with {"page": null} after 60 seconds
while true; do
  curl -s -H "Authorization: Bearer $UPBUTLER_RESPONDER_KEY" \
    "https://upbutler.com/api/v1/responders/me/pages?wait=60"
done

# Or one stream (Server-Sent Events): a frame "event: page" per page, a ping comment every 15s.
# The server ends it after about 10 minutes; reconnect.
curl -N -H "Authorization: Bearer $UPBUTLER_RESPONDER_KEY" \
  "https://upbutler.com/api/v1/responders/me/stream"

{
  "page": {
    "pageId": "pag_0n3q9e55…",
    "deliveries": 1,
    "id": "evt_0n3q9a12c4r7m1t8wxe",
    "type": "incident.page",
    "responder": { "id": "agr_0n3q9c20…", "name": "Claude" },
    "incident": { "id": "inc_0n3q9a11v8k2h5n0qzc", "title": "API is down", "status": "investigating", "impact": "major", "…": "…" },
    "token": { "value": "ub_inc_7q2m…", "type": "Bearer", "expiresAt": "2026-10-14T15:02:13.020Z", "scope": ["…"] },
    "ackTimeoutMinutes": 5,
    "api": { "base": "https://upbutler.com/api/v1", "mcp": "https://upbutler.com/mcp", "packet": "https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/packet", "claim": "https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim" },
    "prompt": "UpButler is paging you (\"Claude\") as the on-call responder. …",
    "packet": { "schema": "upbutler.incident-packet/v1", "…": "…" },
    "receipt": "Confirm receipt with POST https://upbutler.com/api/v1/responders/me/pages/pag_0n3q9e55…/ack, or claim the incident; otherwise this page is delivered again in 30s."
  },
  "waitedMs": 8421
}

// Nothing happened while you waited: ask again
{ "page": null, "waitedMs": 60000, "next": "No page yet. Call again to keep waiting." }

# 1. Receipt: "I have the page". Stops redelivery. It is not a claim.
curl -X POST https://upbutler.com/api/v1/responders/me/pages/pag_0n3q9e55…/ack \
  -H "Authorization: Bearer $UPBUTLER_RESPONDER_KEY"
# → { "pageId": "pag_0n3q9e55…", "received": true, "incidentId": "inc_0n3q9a11v8k2h5n0qzc" }

# 2. Claim, with the incident token from the page. This is what stops escalation.
curl -X POST https://upbutler.com/api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/claim -H "Authorization: Bearer ub_inc_7q2m…"

claude mcp add --transport http upbutler-responder "https://upbutler.com/mcp?toolset=core" \
  --header "Authorization: Bearer $UPBUTLER_RESPONDER_KEY"

You are the on-call responder for Acme. Loop until I stop you:
1. Call responder_wait_for_page. If page is null, call it again.
2. When a page arrives: incidents_claim for page.incident.id, then incidents_packet,
   and follow the runbook in the packet. Nothing outside it.
3. Log each action with incidents_note. Call incidents_claim_renew every few minutes.
4. After a fix: incidents_verify. Call incidents_resolve only if it passed.
5. Runbook doesn't cover it, or two attempts failed: incidents_escalate with what you found.
6. Go back to step 1.

export UPBUTLER_RESPONDER_KEY=ub_rsp_4f1c…

# Claude Code, headless, once per page
npx upbutler responder listen \
  --exec 'claude -p "$UPBUTLER_PROMPT" --allowedTools "Bash,Read,Edit"'

# Or your own script
npx upbutler responder listen --exec ./handle-incident.sh

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

// Reads UPBUTLER_RESPONDER_KEY. Claims each incident, renews the lease while onPage runs,
// and hands the incident to the next level if onPage throws.
await UpButler.responders.listen({
  onPage: async (page, { incident, signal }) => {
    await incident.note('Restarting the API', 'restart');
    await restartApi({ signal });              // your code, or your agent with page.prompt
    const v = await incident.verify();
    if (v.passed) await incident.resolve('The API was restarted and is healthy again.');
    else await incident.escalate('Restarted the API; verify still fails.');
  },
});

// npm install @upbutler/sdk @anthropic-ai/claude-agent-sdk
// UPBUTLER_RESPONDER_KEY=ub_rsp_… ANTHROPIC_API_KEY=sk-ant-… node responder.mjs
import { query } from '@anthropic-ai/claude-agent-sdk';
import { UpButler } from '@upbutler/sdk';

const EXTRA = `
You are already the owner of this incident (it was claimed for you and the claim is renewed while you work).
Use Bash (curl) with the incident token above to call the UpButler API: add a note for every finding and action,
run POST /verify after a fix, resolve only after a passing verify, and escalate if you cannot fix it.`;

await UpButler.responders.listen({
  onTestPage: (page) => console.error(`test page for ${page.responder.name}: the connection works`),
  onPage: async (page) => {
    for await (const message of query({
      prompt: page.prompt + EXTRA,
      options: { cwd: process.env.RUNBOOK_DIR ?? process.cwd(), allowedTools: ['Bash', 'Read'], permissionMode: 'dontAsk', maxTurns: 40 },
    })) {
      if (message.type !== 'result') continue;
      // Throwing makes the listener escalate the incident, so humans are paged.
      if (message.subtype !== 'success') throw new Error(`Claude stopped without finishing (${message.subtype})`);
    }
  },
});

# pip install upbutler openai-agents
# UPBUTLER_RESPONDER_KEY=ub_rsp_… OPENAI_API_KEY=sk-… python responder.py
import json
from agents import Agent, Runner, function_tool
from upbutler import listen

def handle(page, session):
    @function_tool
    def note(message: str) -> str:
        """Add an internal timeline note with a finding or an action you took."""
        session.note(message)
        return "noted"

    @function_tool
    def verify() -> str:
        """Re-check the incident's monitors from every region. Returns JSON with "passed"."""
        return json.dumps(session.verify())

    @function_tool
    def resolve(message: str) -> str:
        """Resolve the incident. Only after verify returned passed: true."""
        session.resolve(message)
        return "resolved"

    @function_tool
    def escalate(reason: str) -> str:
        """Hand the incident back to the humans with what you found."""
        session.escalate(reason)
        return "escalated"

    agent = Agent(
        name="On-call responder",
        instructions="You are the on-call responder for this incident and already own it. Note your findings, "
        "verify, then resolve if verify passes; otherwise escalate with a clear reason. Always end with resolve or escalate.",
        tools=[note, verify, resolve, escalate],  # add your own restart / rollback tools
    )
    # A raised exception (model error, turn limit) makes listen() escalate the incident.
    Runner.run_sync(agent, f"{page['prompt']}\n\nHandoff packet:\n{json.dumps(session.packet())[:60000]}")

listen(on_page=handle)  # reads UPBUTLER_RESPONDER_KEY; blocks

from upbutler import listen
from my_graph import graph   # your compiled LangGraph graph

def handle(page, session):
    result = graph.invoke({"brief": page["prompt"], "packet": page["packet"]})
    session.note(result.get("summary", "Graph finished."))
    if session.verify()["passed"]:
        session.resolve(result.get("resolution"))
    else:
        session.escalate("Graph finished but verify still fails.")

listen(on_page=handle)

{ "text": "{{prompt}}" }   // works, but the prompt contains the incident token

{
  "schema": "upbutler.incident-packet/v1",
  "generatedAt": "2026-10-14T13:02:11.512Z",
  "incident": { "id": "inc_0n3q9a11v8k2h5n0qzc", "title": "API is down", "status": "investigating", "impact": "major",
                "source": "monitor", "public": true, "startedAt": "…", "durationMinutes": 1,
                "acknowledgedBy": null, "claim": null, "lastVerify": null, "url": "…" },
  "monitors": [{
    "id": "mon_0n3q8kz1m4hx7c2v9rt", "name": "API", "kind": "http",
    "target": "https://api.acme.com/health?key=[redacted]",
    "request": { "method": "GET", "expectedStatus": "200-299", "headerNames": ["authorization"], "hasBody": false },
    "state": "down", "since": "…", "intervalSec": 30, "regions": ["eu-central", "de-nbg", "fr-lbg"],
    "lastCheck": { "at": "…", "outcome": "down", "statusCode": 502, "error": "Down from 3 of 3 regions — …" },
    "firstFailureAt": "2026-10-14T13:01:10.000Z",
    "lastGoodCheck": { "at": "2026-10-14T13:00:40.000Z", "region": "de-nbg", "statusCode": 200, "latencyMs": 84 },
    "evidence": [
      { "region": "de-nbg", "regionLabel": "Nuremberg", "at": "…", "outcome": "down", "statusCode": 502,
        "error": "Expected status 200-299, got 502 Bad Gateway", "bodySnippet": "<html>502 Bad Gateway…",
        "responseHeaders": { "server": "nginx" } }
    ],
    "runbook": "## API down\n1. A deploy in the last 30 minutes? …"
  }],
  "components": [{ "id": "cmp_0n3q8kz2p7wd4yx0s3a", "key": "api", "name": "API", "page": "Acme Status",
                   "status": "major_outage", "signal": "major_outage", "source": "monitor" }],
  "deploys": [{ "id": "dep_…", "name": "1.4.2 (commit abc1234)", "version": "1.4.2", "environment": "production",
                "at": "2026-10-14T12:58:55.000Z", "timing": "3 min before the incident started",
                "minutesBeforeIncident": 3, "suspect": true }],
  "relatedIncidents": [{ "id": "inc_…", "title": "API is down", "startedAt": "…", "durationMinutes": 12,
                         "resolution": "Rolled back 1.3.9.", "rootCause": "Bad migration" }],
  "analysis": { "summary": "…", "likelyCauses": ["…"], "suggestedActions": ["…"], "severity": "major" },
  "timeline": [{ "at": "…", "by": "UpButler", "status": "investigating", "public": true, "body": "…" }],
  "runbook": "Prefer rolling back over fixing forward.",
  "guardrails": { "responder": "Claude", "allowedActions": ["note", "public_update", "verify", "resolve", "escalate", "mute"],
                  "publicUpdates": "draft", "leaseMinutes": 15, "resolveRequiresVerifyWithinMinutes": 10,
                  "maxMuteMinutes": 60, "tokenScope": ["GET /api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/packet", "…"] },
  "links": { "dashboard": "…", "statusPages": ["https://acme.upbutler.com"], "packet": "…", "claim": "…",
             "renew": "…", "notes": "…", "publicUpdates": "…", "verify": "…", "resolve": "…", "escalate": "…", "mute": "…" }
}

HTTP/1.1 409 Conflict
{
  "error": {
    "code": "conflict",
    "message": "This incident is claimed by Claude (agent)",
    "hint": "Only one responder works on an incident at a time. Stand down; you are paged again if the claim lapses.",
    "details": { "claimedBy": { "type": "agent", "id": "agr_0n3q9c20…", "name": "Claude" },
                 "since": "2026-10-14T13:02:30.000Z", "expiresAt": "2026-10-14T13:17:30.000Z" }
  }
}

{
  "at": "2026-10-14T13:09:44.120Z",
  "passed": true,
  "summary": "Verification passed: 1 monitor healthy from 3 region checks.",
  "monitors": [{
    "monitorId": "mon_0n3q8kz1m4hx7c2v9rt", "name": "API", "passed": true, "outcome": "up",
    "regions": [
      { "region": "eu-central", "label": "Helsinki",  "outcome": "up", "statusCode": 200, "latencyMs": 91 },
      { "region": "de-nbg",     "label": "Nuremberg", "outcome": "up", "statusCode": 200, "latencyMs": 84 },
      { "region": "fr-lbg",     "label": "Lauterbourg", "outcome": "up", "statusCode": 200, "latencyMs": 102 }
    ]
  }],
  "next": "Healthy. Resolve with POST /api/v1/incidents/inc_0n3q9a11v8k2h5n0qzc/resolve within 10 minutes."
}

# Any monitor, by a person or a full API key (agents: up to 60 minutes)
curl -X POST https://upbutler.com/api/v1/monitors/mon_0n3q8kz1m4hx7c2v9rt/mute \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" -H "Content-Type: application/json" \
  -d '{"minutes": 15, "reason": "Restarting the worker pool"}'

curl -X POST https://upbutler.com/api/v1/monitors/mon_0n3q8kz1m4hx7c2v9rt/unmute -H "Authorization: Bearer $UPBUTLER_API_KEY"

# 1. Ship, then ask UpButler to watch
curl -X POST https://upbutler.com/api/v1/deploys/guard \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploy": { "version": "1.4.2", "commit": "abc1234def", "service": "api" },
    "minutes": 10,
    "callbackUrl": "https://ci.acme.com/hooks/upbutler"
  }'
# → { "_id": "grd_0n3q9d31…", "status": "watching", "signingSecret": "whsec_…", "secondsLeft": 600, … }

# 2. No public endpoint? Poll instead
curl https://upbutler.com/api/v1/deploys/guards/grd_0n3q9d31… -H "Authorization: Bearer $UPBUTLER_API_KEY"

{
  "id": "evt_0n3q9d40…",
  "type": "deploy.guard.verdict",
  "timestamp": "2026-10-14T13:01:40.000Z",
  "data": {
    "guard": {
      "id": "grd_0n3q9d31…",
      "status": "regression",
      "deployId": "dep_0n3q9d30…",
      "deploy": "1.4.2 (commit abc1234)",
      "startedAt": "2026-10-14T12:58:55.000Z",
      "endsAt": "2026-10-14T13:08:55.000Z",
      "monitorIds": ["mon_0n3q8kz1m4hx7c2v9rt"],
      "preexisting": [],
      "verdict": {
        "at": "2026-10-14T13:01:40.000Z",
        "status": "regression",
        "summary": "Regression after deploy 1.4.2 (commit abc1234): API is down (Expected status 200-299, got 502 Bad Gateway).",
        "regressions": [{ "monitorId": "mon_0n3q8kz1m4hx7c2v9rt", "name": "API", "state": "down", "since": "…", "incidentId": "inc_0n3q9a11v8k2h5n0qzc" }],
        "recommendation": "rollback"
      }
    }
  }
}