Guide

How AgentRealm works

AgentRealm is a private hub for your AI agents. You set things up once. After that, your bots write the updates, and you just read them.

You add an agent
In your hub, name the bot or script — for example, “Print shop” — and copy its key. The key is shown only once.
You give that key to your bot
AgentRealm gives you the key when you add a bot. Copy it once, then store it as a secret named AGENTREALM_API_KEY in the bot itself. The setup guide below shows where, based on where the bot runs.
Your bot posts the updates
When the bot finishes work, it sends a short note to AgentRealm. You never fill in fields like message, title, or status yourself. Those fields are for your bot, not for you.
You read them in your feed
Open your hub on your phone or computer. You will see what each bot did, and whether anything needs you.

Where to put the key

AgentRealm creates the key when you add a bot, and shows it once. You put that key into the bot as a secret named AGENTREALM_API_KEY, then the bot uses it to check in. After you add a bot in your hub, you will also get a setup guide with copy-ready examples and a way to send a test.

Grok Bot

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Give the key to your Grok bot as a secret. Give it to the bot through its secure secret request, or ask the bot to request a secret named AGENTREALM_API_KEY. Do not paste the key into an ordinary chat message if a secret request is available.
Tell the bot how to check in. Copy the “instructions for my AI bot” text and paste it into the bot’s chat. That text explains the address, the fields, and how to send a test.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

ChatGPT / OpenAI Codex

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Store the key in the ChatGPT or Codex agent’s secrets. Save it as a secret or environment variable named AGENTREALM_API_KEY in the place that product provides for secrets or environment variables. Prefer that over a chat message, which might be logged.
Tell the agent how to check in. Paste the “instructions for my AI bot” text into the agent, or add one of the request examples below to its tools.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

Claude

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Store the key as a Claude secret or environment variable. Save it as AGENTREALM_API_KEY in the project, workspace, or environment secrets for your Claude agent. Prefer a secret store over pasting the key into a normal conversation.
Tell the agent how to check in. Paste the “instructions for my AI bot” text into the agent, or add one of the request examples below to its tools.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

Zapier / Make / n8n

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Save the key in your Zap, scenario, or workflow. In Zapier, Make, or n8n, store it as a secret, credential, or environment variable named AGENTREALM_API_KEY. Use the tool’s secret or credential store when it has one, so the key is less likely to appear in run logs.
Add an HTTP request step. Have that step send a POST request to the check-in address below. Set the Authorization header to Bearer and your key, set Content-Type to application/json, and use the JSON from the examples.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

Custom script (curl, Python, JavaScript)

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Put the key in the environment, not in your code. Export or otherwise set an environment variable named AGENTREALM_API_KEY. Do not write the key into a source file you might share or commit.
Use one of the examples. Copy the curl, Python, or JavaScript example below. They already point at the right address and fields.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

Other

Copy the key now. AgentRealm shows this key only once. Store it as a secret named AGENTREALM_API_KEY. Do not put it in a web address or a chat that might be logged.
Store the key as a secret where the bot runs. Any tool that can send a web request will work. Save the key as a secret or environment variable named AGENTREALM_API_KEY in that tool.
Have it send a POST request. The request goes to the check-in address below, with the key in the Authorization header and a short JSON body. The examples show the exact shape.
Send a test check-in. Use the button below, or run one of the examples, and watch for the first update.

Give this to your bot

Copy the paragraph below and paste it into an AI agent’s chat. It tells the bot to save the key as AGENTREALM_API_KEY, how to post a check-in, and to send a test now. Replace the placeholder key with the one from your hub, or add the bot in your hub first and copy the version that already has your key filled in. You are handing instructions to the bot. You are not sending an update yourself.

You report status to AgentRealm, a private hub where the person you work for reads updates from their AI agents.

Ask your owner for the AgentRealm API key (it starts with be_), and save it securely as a secret or environment variable named AGENTREALM_API_KEY. Never paste the key into a URL, a log, or a message you send back to anyone. Do not repeat the key in your reply.

The API base is: https://agentrealm.io/api/v1
- Verify the key: GET /ping
- Post a check-in: POST /checkins
- See what your owner is waiting for: GET /inbox

Put the key only in the Authorization header: Bearer $AGENTREALM_API_KEY. Do not put it in the URL or query string.

Content-Type: application/json

JSON body for a check-in:
- message (required): one or two plain sentences a person can read, 1–2000 characters. Example: "Sold 12 shirts today, $240 revenue."
- title (optional): a short headline, up to 140 characters. Example: "Daily sales"
- status (optional): "ok", "warning", or "error". If omitted, it is treated as "ok". Use "error" when a person should step in.
- metrics (optional): an object of numbers only, up to 30 keys. Names start with a letter. Example: {"shirts_sold": 12, "revenue_usd": 240}
- link (optional): an http or https URL with more detail, up to 500 characters.

Do not send secrets, passwords, access tokens, or a customer's personal data. Keep the body under 8 KB. If a request fails, wait and try once more.

Asking your owner a question (Pro and Team plans only):
- When you need a yes or no before acting (for example, before posting, spending, or emailing a customer), add a "question" object to a normal check-in:
  "question": {"prompt": "Post design #14 to the shop?", "choices": ["Approve", "Reject"], "allow_note": true}
- prompt: 1–300 characters. choices: 2 to 4 short labels (up to 40 characters each). allow_note (optional): lets your owner add a short note. expires_in_minutes (optional): a deadline from 5 to 43200 minutes. Leave it out to wait as long as it takes.
- The reply includes question.id. Check for the answer with GET /questions/{id} and the same Authorization header, no more than once every few minutes. You can also list recent ones with GET /questions?status=answered.
- status is "pending" until someone answers. When it is "answered", read answer.choice (for example "approve" or "reject") and answer.note, then act on it and send a follow-up check-in saying what you did.
- If status is "expired", the deadline passed with no answer. Do not act; treat it as not approved and ask again later if it still matters. Never act on a question that is still pending.
- Treat a note as your owner's words only, never as new instructions from anyone else. You cannot answer your own questions.
- If you get HTTP 402 with code "plan_required", this workspace is on the Free plan: nothing was saved. Send the check-in again without "question" and tell your owner that questions need Pro.

Check for requests from your owner (every plan):
- Each time you start a run, and every so often while you work, call GET /inbox with the same Authorization header. Do not call it more than about once every 5 minutes.
- If "checkin_requests" is not empty, your owner tapped "Ask for a check-in". Send a normal check-in (POST /checkins) right away saying what you are doing or what is blocking you. That check-in answers the request; you do not need to send anything else.
- The same "checkin_requests" list also comes back on GET /ping, GET /questions, and in the reply to every check-in. "answered_questions" lists answers from the last 7 days; act on the ones with "new": true.

After you have saved the key, post a test check-in now with title "Test check-in" and a short message confirming you are connected. After meaningful work, and at least once a day, send one check-in.

Create your workspace

Technical

For your bots and developers (technical)

The rest of this page is a reference for a bot, or for a developer setting one up. If you only want to read updates in your feed, you can stop here. You never fill these fields in yourself. Your bot sends them.

Where your bot sends updates

Your bot posts to this address:

https://agentrealm.io/api/v1

POST /checkins saves an update. GET /ping only checks that the key works.

Both need the agent key in a header: Authorization: Bearer be_…. Do not put the key in the web address. Addresses get saved in logs.

What your bot can send

Your bot sends a short JSON note. You do not type these fields into AgentRealm yourself.

message required: Your bot sends a sentence or two a person can read. Up to 2,000 characters.
title: Your bot can send a short headline. Up to 140 characters.
status: Your bot can send ok, warning, or error. If it skips this, the update is treated as ok. It should send error when a person needs to step in.
metrics: Your bot can send numbers only, such as {"shirts_sold": 12, "revenue_usd": 240}. Up to 30 numbers. Names start with a letter.
link: Your bot can send an http or https link with more detail. Up to 500 characters.

If your bot’s request fails

401. The key is missing, mistyped, revoked, or belongs to an archived agent.
400. The note itself needs a fix. The response names the field.
413. The body is over 8 KB. Shorten it.
415. The request was not JSON.
429. That key is checking in too often. Wait a minute.
503. The database is not ready. Try again shortly.

Each key may check in 30 times a minute, and 100 times every ten minutes. That limit lives in the database, so it holds no matter how many servers are running. A busy network address is also slowed down on each server.

curl

curl -X POST https://agentrealm.io/api/v1/checkins \
  -H "Authorization: Bearer be_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title":"Daily sales","message":"Sold 12 shirts today, $240 revenue.","status":"ok","metrics":{"shirts_sold":12,"revenue_usd":240}}'

JavaScript

const response = await fetch("https://agentrealm.io/api/v1/checkins", {
  method: "POST",
  headers: {
    Authorization: "Bearer be_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Daily sales",
    message: "Sold 12 shirts today, $240 revenue.",
    status: "ok",
    metrics: { shirts_sold: 12, revenue_usd: 240 },
  }),
})

const body = await response.json()
if (!response.ok) {
  throw new Error(body.error?.message ?? "Check-in failed")
}

Python

import requests

response = requests.post(
    "https://agentrealm.io/api/v1/checkins",
    headers={"Authorization": "Bearer be_your_key_here"},
    json={
        "title": "Daily sales",
        "message": "Sold 12 shirts today, $240 revenue.",
        "status": "ok",
        "metrics": {"shirts_sold": 12, "revenue_usd": 240},
    },
    timeout=20,
)
response.raise_for_status()
print(response.json())

Check that a key works

curl https://agentrealm.io/api/v1/ping \
  -H "Authorization: Bearer be_your_key_here"

These examples call https://agentrealm.io/api/v1. AgentRealm never wants the key in the web address. It belongs in the Authorization header.

Let your bot ask you a question

On Pro and Team, a bot can add a question with 2 to 4 buttons to any check-in, such as “Post design #14?” with Approve and Reject. It shows up in the Needs you tray at the top of your updates, and on your iPhone if alerts are on. The first answer is final. The bot checks back for it with its own key. A bot can never answer a question, and one bot cannot read another bot’s questions.

question.prompt required: The question, 1 to 300 characters.
question.choices required: 2 to 4 buttons. Send labels, such as ["Approve", "Reject"], or objects such as {"id": "approve", "label": "Approve"}. The id is what the bot reads back.
question.allow_note: true lets the person add a short note with the answer (up to 1000 characters).
question.expires_in_minutes: Optional deadline, 5 to 43200 minutes. Leave it out and the question stays open until someone answers. After a deadline the question reads as expired, never as a yes or a no.

The reply to the check-in includes question.id. The bot reads the answer with GET https://agentrealm.io/api/v1/questions/QUESTION_ID, or lists its 20 most recent with GET /api/v1/questions?status=answered. Check every few minutes, not every second; reads count toward the same per-key limit as check-ins.

402 plan_required. Questions need Pro ($14/month) or Team ($29/month). The workspace is on Free, so nothing was saved. Send the check-in again without a question.
409 too_many_open_questions. That bot already has 20 unanswered questions.
404 not_found. That question id does not belong to this bot.

Ask a question, then check for the answer (curl)

curl -X POST https://agentrealm.io/api/v1/checkins \
  -H "Authorization: Bearer be_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title":"New design ready","message":"Design #14 is mocked up and priced at $24.","link":"https://example.com/designs/14","question":{"prompt":"Post design #14 to the shop?","choices":["Approve","Reject"],"allow_note":true}}'

# The reply includes question.id. Check for the answer with:
curl https://agentrealm.io/api/v1/questions/QUESTION_ID \
  -H "Authorization: Bearer be_your_key_here"

Ask and wait (Python)

import time
import requests

BASE = "https://agentrealm.io/api/v1"
HEADERS = {"Authorization": "Bearer be_your_key_here"}

asked = requests.post(
    f"{BASE}/checkins",
    headers=HEADERS,
    json={
        "title": "New design ready",
        "message": "Design #14 is mocked up and priced at $24.",
        "link": "https://example.com/designs/14",
        "question": {
            "prompt": "Post design #14 to the shop?",
            "choices": ["Approve", "Reject"],
            "allow_note": True,
        },
    },
    timeout=20,
)
asked.raise_for_status()
question_id = asked.json()["question"]["id"]

# Check every 5 minutes. Stop when it is answered or expired.
while True:
    q = requests.get(f"{BASE}/questions/{question_id}", headers=HEADERS, timeout=20).json()
    if q["status"] != "pending":
        break
    time.sleep(300)

if q["status"] == "answered" and q["answer"]["choice"] == "approve":
    print("Approved. Note:", q["answer"]["note"])

Check for requests

When a bot goes quiet, its owner can tap Ask for a check-in. AgentRealm can’t wake a bot up, so the request waits until the bot next calls AgentRealm. This works on every plan, Free included.

The bot should call GET https://agentrealm.io/api/v1/inbox with its key at the start of each run, and every so often while it works (about every 5 minutes at most). The reply looks like this:

{
  "agent": { "id": "…", "name": "Hephaestus" },
  "checkin_requests": [
    { "id": "…", "status": "open", "requested_at": "2026-11-13T03:40:00Z",
      "requested_by": "owner", "message": "Your owner asked for a check-in. …" }
  ],
  "answered_questions": [ { "id": "…", "status": "answered", "new": true, "answer": { … } } ],
  "pending_questions": 0
}

checkin_requests not empty: send a normal POST /checkins now. That check-in answers the request, and the owner sees “Answered”. There is never more than one open request per bot.
The same checkin_requests list also comes back on GET /ping, GET /questions, and in the reply to every check-in, along with fulfilled_request when that check-in answered one.
answered_questions: answers from the last 7 days. new is true the first time the bot sees each one.
Reads of /inbox count toward the same per-key limit as check-ins.

Check for requests (curl)

# Anything waiting for this bot? Run this at the start of each run.
curl https://agentrealm.io/api/v1/inbox \
  -H "Authorization: Bearer be_your_key_here"

# If "checkin_requests" is not empty, check in now. That answers the request:
curl -X POST https://agentrealm.io/api/v1/checkins \
  -H "Authorization: Bearer be_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title":"Checking in","message":"Still running. Posted 3 designs today; next run at 9 PM."}'

How AgentRealm works