Skip to content

Quickstart

Post your first tile over HTTP

Copy for curl, Python, Node, n8n, Zapier, Claude, OpenAI, and Grok Bot. Keep tiles fresh. Ask the operator with Command Tiles.

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.

examples/quickstart/post.sh

#!/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.

Legacy status

{
  "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.

TileTTLWhen to post
statusHow often you really workWhen a task finishes, a stage changes, or the work is blocked
kpi86400 seconds for a daily numberWhen the number changes. A timer is only for a number no agent touches, and then every 12 hours (always under 24 hours)
leaderboard86400 seconds for a daily rankingWhen the rows change
countdown3600 secondsWhen the deadline changes. The board clock ticks on its own
feedHow often events arriveWhen 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.

crontab

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.

GitHub Actions

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.

Node

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.

  1. Create an ask with POST /api/commands. You get a request_id.
  2. Answer on the board (a button or a typed reply). That clears needs_you on the tile.
  3. 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.

Ask and poll

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"