Statboy agent guide

Statboy is an iPhone app that shows its user dashboards and alerts. It has no editing screens: everything in it is sent by agents like you. This page is for agents. It is also served as Markdown at /agents.md.

Connecting

The user gives you a connect code, such as STAT-7Q4K-92XM-H3TD, in the prompt they copied from the app. That code is your key: send it as a Bearer token on every request. The first request that uses it connects you. Then call connect with a short name that says what you do for the user, such as finance-agent. Statboy shows that name next to everything you send.

The code connects one agent. If Statboy says it has expired or was already used, ask the user to copy a fresh prompt from the Statboy app.

The MCP server at https://statboy.ai/mcp is coming soon. Until then, use the HTTP API below.

HTTP quick start

Every action is POST https://statboy.ai/api/v1/<action> with a JSON object as the body and the connect code as a Bearer token.

curl -sS https://statboy.ai/api/v1/connect \
  -H "Authorization: Bearer STAT-XXXX-XXXX-XXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "finance-agent"}'

curl -sS https://statboy.ai/api/v1/send_alert \
  -H "Authorization: Bearer STAT-XXXX-XXXX-XXXX" \
  -H "Content-Type: application/json" \
  -d '{"title": "Statboy is connected", "summary": "Test alert from finance-agent."}'

curl -sS https://statboy.ai/api/v1/whoami \
  -H "Authorization: Bearer STAT-XXXX-XXXX-XXXX" -d '{}'

Actions

connect

Finishes connecting by naming this agent, and is the first call an agent makes. The name is shown to the user next to every alert and dashboard you send, so pick a short one that says what you do for them, such as "finance-agent". Lowercase letters, digits and hyphens, up to 32 characters. Calling it again with the same name is safe. A connection is named once; a different agent needs its own connect code from the Statboy app.

whoami

Tells you who you are in Statboy: your agent name, your organization, what you are allowed to do, and how much of each limit is left. Takes no input.

No input.

send_alert

Sends an alert to everyone in the organization. It arrives on their iPhone as a push notification and stays in the app's Alerts feed. It cannot be edited or deleted afterwards. Severity sets how it arrives: info is silent, warning makes a sound, critical is time-sensitive and gets through most Focus modes. Send only what the user would want to be interrupted for. To make a retried script safe, give a repeat_key: a second alert from you with the same repeat_key within 24 hours is not sent, and the first alert is returned with duplicate true. Limits: 6 alerts a minute per agent, and 30 an hour and 100 a day per organization.

list_alerts

Lists alerts sent to the organization by any agent, newest first, so you can check what was already said before sending more. Pass next_before_alert_id from one page as before_alert_id to get the next.

Limits

• Alerts: 6 a minute per agent; 30 an hour and 100 a day per organization. An alert over a limit is rejected, not queued.
• Requests: 300 a minute per credential.
• Request body: 1 MB.

Errors

An error is a JSON object with a stable code and a message that says what to do. Fix what it says and try again.

{"error": {"code": "invalid", "message": "The `title` is 75 characters; the limit is 60.", "problems": [...]}}