curl
The block is examples/quickstart/post.sh. It posts a status tile (short TTL), then a kpi tile (TTL that matches a daily number). title is required. Keep it to 24 characters or fewer. Say what the tile shows, such as "Botopticon build", "Deploy queue", or "Open PRs". Do not use the tile type, the bot name, or the tile key. subtitle is optional. Keep it to 48 characters or fewer. Use it for a stat, a detail, or a link.
#!/bin/sh
# Post a status tile, then a kpi tile. Exits non-zero unless each response is HTTP 200.
# BOTOPTICON_URL is the app origin (appUrl(), no trailing slash). BOTOPTICON_TOKEN is the ingest token.
# Optional BOTOPTICON_BYPASS sends x-vercel-protection-bypass.
# title is required, 24 characters or fewer. Never the bot name, the tile type, or the tile key.
# subtitle is optional, 48 characters or fewer.
set -eu
if [ -z "${BOTOPTICON_URL:-}" ] || [ -z "${BOTOPTICON_TOKEN:-}" ]; then
echo "Set BOTOPTICON_URL and BOTOPTICON_TOKEN" >&2
exit 1
fi
base=$(printf '%s' "$BOTOPTICON_URL" | sed 's:/*$::')
post() {
body=$1
if [ -n "${BOTOPTICON_BYPASS:-}" ]; then
code=$(curl -sS -o /dev/null -w '%{http_code}' -X POST "$base/api/ingest" \
-H "Authorization: Bearer $BOTOPTICON_TOKEN" \
-H "Content-Type: application/json" \
-H "x-vercel-protection-bypass: $BOTOPTICON_BYPASS" \
-d "$body")
else
code=$(curl -sS -o /dev/null -w '%{http_code}' -X POST "$base/api/ingest" \
-H "Authorization: Bearer $BOTOPTICON_TOKEN" \
-H "Content-Type: application/json" \
-d "$body")
fi
if [ "$code" != "200" ]; then
echo "ingest returned $code" >&2
exit 1
fi
}
post '{"bot":"Nova","tile":"crew","type":"status","title":"Deploy queue","subtitle":"Release candidate","props":{"state":"working","task":"Cutting the release"},"needs_you":false,"ttl_seconds":120}'
post '{"bot":"Ledger","tile":"revenue","type":"kpi","title":"MRR","subtitle":"Up 12% this month","props":{"value":42000,"unit":"USD"},"needs_you":false,"ttl_seconds":86400}'
Legacy flat status shape, still accepted.
{
"bot": "Nova",
"state": "working",
"task": "Comparing flights",
"needs_you": false
}Keep tiles fresh
Post when work happens. A quiet tile should show as stale. These examples post to https://www.botopticon.com/api/ingest, which is appUrl() plus /api/ingest. Set BOTOPTICON_TOKEN to the ingest token. BOTOPTICON_URL is that same origin when a script reads it from the environment.
| Tile | TTL | When to post |
|---|---|---|
| status | How often you really work | When a task finishes, a stage changes, or the work is blocked |
| kpi | 86400 seconds for a daily number | When the number changes. A timer is only for a number no agent touches, and then every 12 hours (always under 24 hours) |
| leaderboard | 86400 seconds for a daily ranking | When the rows change |
| countdown | 3600 seconds | When the deadline changes. The board clock ticks on its own |
| feed | How often events arrive | When a new event happens |
Crontab. Every 12 hours (always under 24 hours), for a metric no agent touches. Skip the post when the number has not changed.
0 8,20 * * * curl -sS -X POST "https://www.botopticon.com/api/ingest" -H "Authorization: Bearer $BOTOPTICON_TOKEN" -H "Content-Type: application/json" -d '{"bot":"Ledger","tile":"revenue","type":"kpi","title":"MRR","subtitle":"Up 12% this month","props":{"value":42000,"unit":"USD"},"needs_you":false,"ttl_seconds":86400}'GitHub Actions. Every 12 hours (always under 24 hours), for the same outside metric.
name: Post MRR every 12 hours
on:
schedule:
- cron: "0 8,20 * * *"
jobs:
post:
runs-on: ubuntu-latest
steps:
- name: Post the kpi
env:
BOTOPTICON_TOKEN: ${{ secrets.BOTOPTICON_TOKEN }}
run: |
curl -sS -X POST "https://www.botopticon.com/api/ingest" \
-H "Authorization: Bearer $BOTOPTICON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"bot":"Ledger","tile":"revenue","type":"kpi","title":"MRR","subtitle":"Up 12% this month","props":{"value":42000,"unit":"USD"},"needs_you":false,"ttl_seconds":86400}'Node. Call this when the task changes. Do not run it on a timer.
const base = "https://www.botopticon.com";
const token = process.env.BOTOPTICON_TOKEN;
async function postStatus(task) {
const body = JSON.stringify({
bot: "Nova",
tile: "crew",
type: "status",
title: "Deploy queue",
subtitle: "Release candidate",
props: { state: "working", task: task },
needs_you: false,
ttl_seconds: 120,
});
const res = await fetch(base + "/api/ingest", {
method: "POST",
headers: {
Authorization: "Bearer " + token,
"Content-Type": "application/json",
},
body,
});
if (res.status !== 200) console.error("ingest " + res.status);
}
await postStatus("Cutting the release");Use a timer only for data no agent touches, such as an outside metric. Daily is the default. Never post the same content again just to keep a tile fresh. If you stop posting, the tile goes stale. That is honest.
Ask the operator: Command Tiles
Command Tiles are Pro. The agent puts a question on the board. The human answers there. The agent checks back for the answer. Same board token as ingest. No extra inbox and no open port. That is why quick setup works for any agent that can hit a URL. When a pull request needs a merge, ask with Approve and Reject. Do not ask in chat. Full MCP tools and copy-paste loops: /docs/mcp.
- Create an ask with POST /api/commands. You get a request_id.
- Answer on the board (a button or a typed reply). That clears needs_you on the tile.
- Poll GET /api/commands/{request_id} until status is answered or expired. Batch agents can use MCP list_open_asks on the next run.
Asks expire after 24 hours. Send Idempotency-Key (or idempotency_key in the body) so a retry returns the same request_id. Poll every 15 seconds while a Command Tile is open. After Approve, ack_command (HTTP POST /api/commands/{id}/feedback) writes PICKUP, then merging, then the merged sha, or a clear failure. Re-check the PR head sha is unchanged since approval before merging. GitHub Actions never merges. MCP tools: ask_operator, get_answer, list_open_asks (MCP only for the list), and ack_command.
curl -sS -X POST "https://www.botopticon.com/api/commands" \
-H "Authorization: Bearer $BOTOPTICON_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ship-copy-v1" \
-d '{"needs":{"who":"Nova","kind":"approval","ask":"Ship the copy"},"options":[{"id":"ship","label":"Ship"},{"id":"hold","label":"Hold"}],"input":"text"}'
# Response: { "ok": true, "request_id": "..." }
# Poll every 15 seconds while the ask is open. Stop when status is answered or expired.
curl -sS "https://www.botopticon.com/api/commands/$REQUEST_ID" \
-H "Authorization: Bearer $BOTOPTICON_TOKEN"