IT BOTHub
Sign inTalk to us
Menu

API and MCP

One key per bot, one key per person. The same tools over MCP and over REST. The hub is never in a bot's hot path.

Connect

Send the key as a bearer token. ibb_… is a bot, ibh_… is a person. REST twins live under /api/v1/… and take the same header. Files go to POST /api/v1/files as multipart.

MCP endpoint · Streamable HTTP
https://hub.itbotsolution.com/api/mcp
Claude Code
claude mcp add --transport http itbothub https://hub.itbotsolution.com/api/mcp --header "Authorization: Bearer ibb_…"
REST · pull the structure by version
curl "https://hub.itbotsolution.com/api/v1/structure?ifVersion=14" \
  -H "Authorization: Bearer ibb_…"
# → {"changed":false,"version":14} when nothing moved

Pull (by version)

What a bot reads on start and when told something changed. Pass the version you hold and the hub answers with nothing when nothing moved.

get_structure
The bot's member: groups, bots, reporting lines, channels, contact roles. Pass ifVersion to get {changed:false} when nothing moved.
get_rules
Every rule on the bot's scope chain, most specific first.
get_contacts / get_contact
The member's directory (no more than the bot may see), or one contact by phone or email.
get_channels
Numbers and addresses the member owns, with default bots.
resolve_inbound
Given a channel address and a sender identity: the contact, its reach, and which bot should answer, or UNKNOWN.

Push (backups and events)

What a bot sends back. All of it is a copy; the bot keeps working from its own store.

heartbeat
I am alive. Bots with expectedEveryMin raise an alert when this stops.
log_event
A log line, a report, an error, anything. Free-form type, severity, payload. Returns an upload link for files.
backup_prompt
Hash first: {hash} → {known:true} means send nothing more. Otherwise send prompt and notes; a new version is kept.
backup_rules
The rules as the bot understands them. The hub compares them with its own and raises rule_drift.
thread_note
One note per conversation: which rule applied, the decision, the confidence.
suggest_improvement
What should improve: prompt, rule, code, process or product, with the why and the source thread.
open_task / update_task
The task bridge.
request_upload_link
A one-tap signed link for files a chat client cannot send.

Optional

For bots that want to ask before acting, or people using a key from a script.

check
Ask when unsure: {decision: allow|deny|ask, matched rules, reason}.
set_rule
Propose a default rule (needs an edit grant and the flag on).
whoami
Which bot or person this key is, and its reach.

A bot's day

The order a well-behaved bot calls things in. Nothing here blocks a reply.

  1. On startPull, keep the copy
    • get_structure
    • get_rules
    With the last version you hold. Keep the copy where the bot runs.
  2. Per threadResolve once, note once
    • resolve_inbound
    • get_contact_history
    • thread_note
    Resolve once, cached; reply on the pipe; one note at the end.
  3. Every few minutesHeartbeat, then events
    • heartbeat
    • log_event
    Heartbeat on a timer. An event when something happens.
  4. When the prompt changesHash first
    • backup_prompt
    • suggest_improvement
    Back the prompt up hash-first. When people keep asking for something, suggest it.

Ask for a key