the platform
one action registry. three doors in.
every capability in nihmbus — missions, drafts, engagements, CRM, workflows, search — is defined once in a single action registry. from that one definition, it's exposed as a UI page, an API endpoint, and an AI agent tool. they run the same handler with the same validation. they can never drift apart.
the action registry
one definition. UI, API, and AI — for free.
every action declares a name, a Zod input schema, a handler, and whether it mutates state. from that single definition, the platform generates three surfaces automatically. add an action once and it shows up everywhere.
one definition, three surfaces
every action is defined once — name, Zod input schema, handler, mutating flag. from that one definition it appears as a UI page, an API endpoint, and an AI agent tool. they can never drift apart.
same handler, same validation
the API validates request bodies with the same Zod schema the AI SDK validates tool arguments with. the same handler function runs in all three cases. no parallel implementations.
mutating flag drives approvals
each action declares whether it mutates state. supervised agents queue mutating actions as decisions for human approval. the UI uses the same flag to refresh after writes. one signal, three consequences.
role-based access
actions optionally require specific workspace roles. the same role check runs whether the call comes from the UI, the API, or the agent — no surface-specific bypass.
auto-generated reference
the reference docs are generated directly from the action registry. every action's schema, method, description, and examples are always in sync with the running platform.
discoverable by agents
every action carries a description and optional LLM hints that tell the agent when to reach for it. the agent's tool list is the action registry — not a separate, hand-curated mapping.
in practice
every action, three ways.
here's how real platform actions map across all three surfaces. the agent calls missions_create. the API accepts POST /api/invoke/missions.create. the UI shows /missions. same handler. same validation.
the API surface
every button in the UI is an API call.
authenticate with an API key and call any action via the universal dispatcher at /api/invoke/<action.name>. the same Zod schema validates your request body. the same handler runs. the same response comes back.
build custom integrations, trigger campaigns from CI, pipe data into research datasets, or embed nihmbus into your own product — all through the same surface the agent uses internally.
# Create a mission via the API — same handler as the UI and the agentcurl -X POST https://app.nihmbus.ai/api/invoke/missions.create \ -H "Authorization: Bearer $NIHMBUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "subjectId": "sub_abc123", "name": "Q3 product launch", "autonomyLevel": "supervised" }' # The agent calls the same action as a tool:# missions_create({ subjectId: "sub_abc123", name: "Q3 product launch" })## The UI calls the same handler when you click "New Mission".# One definition. Three doors.autonomy & approvals
control how much the agent can do.
the same 'mutating' flag that the API uses for safety drives the agent's approval queue. supervised agents can't publish without your OK. autonomous agents run end-to-end. change the dial at any time.
autonomy dial
set per-mission autonomy: supervised agents propose every action as a decision. semi-autonomous agents auto-execute reads and file decisions for writes. fully autonomous agents run end-to-end.
decision queue
when a supervised agent wants to publish a post or send an outreach message, it files a decision. approve, reject, or modify — all from the unified inbox.
audit trail
every action — whether executed by a human, approved via decision, or auto-executed by an autonomous agent — is logged with actor, timestamp, and context. full compliance visibility.
extensions & MCP
extend the surface. keep the guarantees.
install extensions that add agent tools (via MCP servers), UI panels, API endpoints, named actions, and workspace-scoped data. extensions plug into the same registry — same validation, same RBAC, same approval system.
skills (playbooks)
a SKILL.md markdown file that orchestrates tools — a reusable procedure the agent follows. ClawHub and Anthropic Agent Skills compatible. import from the community or write your own.
MCP tool servers
extensions contribute executable tools via remote MCP servers (Streamable-HTTP or SSE). the tools merge into the agent's registry, namespaced by extension. the agent calls them like native actions.
UI panels
extensions can ship client-side React panels that appear in the sidebar under /x/<extension>. trusted extensions run with ambient authority; untrusted ones are sandboxed in iframes.
named actions
extensions can declare their own named actions — exposed through /api/invoke and optionally as agent tools. same registry, same validation, same RBAC.
workspace-scoped data
extensions get a built-in key-value store, workspace-scoped and permission-gated. read/write access requires the data.read / data.write permissions granted at install.
enforced permissions
extensions declare required permissions. the subset granted at install is stored and enforced at runtime. an action or API route that requires a permission the extension doesn't have is rejected (403).
MCP integration
your tools, in the agent's hands.
declare an MCP server in your extension manifest. nihmbus connects as an MCP client, merges your tools into the registry (namespaced ext__<name>__<tool>), and the agent can call them like native actions.
- Streamable-HTTP and SSE transports supported
- tool allowlists and mutating-tool declarations in the manifest
- secrets encrypted at rest (AES-256-GCM), injected into headers only
- works with the same approval system as native actions
# MCP server manifest (nihmbus.extension.json){ "name": "my-extension", "displayName": "Custom Analytics", "mcp": { "transport": "streamable-http", "url": "https://mcp.example.com/mcp", "authSecret": "MY_API_KEY", "toolAllowlist": ["analyze_sentiment", "generate_report"], "mutatingTools": ["generate_report"] }, "skills": [{ "path": "skills/weekly-report" }], "permissions": ["data.read", "data.write"]} # Once installed, the agent gains two new tools:# ext__my_extension__analyze_sentiment# ext__my_extension__generate_report# Both appear in the agent's tool registry alongside native actions.data infrastructure
pgvector, hybrid search, explainable AI.
the platform is built on PostgreSQL with pgvector, pg_trgm, and tsvector. every entity is embedded, every search is hybrid-ranked, and every content score is explainable. the agent's intelligence starts in the data layer.
pgvector embeddings (1536-d)
subjects, contacts, knowledge sources, knowledge chunks, content drafts, agent memories, tickets, and search documents are all embedded as 1536-dimension vectors. every entity is semantically searchable.
HNSW indexes
every embedding column is indexed with HNSW (vector_cosine_ops) for sub-millisecond approximate nearest-neighbour queries. the agent can find the most relevant knowledge chunk in microseconds.
hybrid search (RRF)
the search engine fuses three independent signals — full-text (tsvector + GIN), fuzzy trigram (pg_trgm word_similarity), and vector cosine (pgvector) — with Reciprocal Rank Fusion (k=60). no single signal dominates.
headless browser sessions
platforms without APIs are reached via persistent headless browser sessions. the agent logs in once and reuses the cookies — no developer app required. sessions are health-checked daily.
explainable content scoring
every generated draft gets a 0–1 score from five real structural signals: pillar fit, novelty (vector distance), voice fit, constraint fit (platform character limits), and historical engagement. no black-box scores.
semantic content dedup
before generating content, the agent runs a cosine lookup against every existing draft in the mission. near-duplicates are rejected before they waste a generation cycle. in-memory cosine pass deduplicates within a single batch.
frequently asked questions
the architecture, explained.
what does 'one action, three surfaces' mean in practice?
it means every capability — creating a mission, generating a draft, responding to an engagement — is defined once in code. that single definition automatically becomes a UI page, a REST API endpoint, and an AI agent tool. you never have to build, maintain, or document three separate implementations.
can I use the API without the UI?
yes. the API is a full-access surface. everything you can do in the dashboard you can do via HTTP calls. authenticate with an API key, call /api/invoke/<action.name>, and get the same result as clicking the button in the UI.
what is MCP and why does it matter?
MCP (Model Context Protocol) is the standard for connecting AI agents to external tools. nihmbus extensions contribute tools via MCP servers. this means any MCP-compatible agent — not just the built-in nihmbus agent — can use your extensions. it's an open standard, not a proprietary lock-in.
can external AI agents control nihmbus?
yes. because every action is an API endpoint and an MCP tool, external agents (claude, cursor, custom agents) can drive nihmbus programmatically. connect an MCP client to the nihmbus action registry and the external agent gets the same tool surface as the built-in one.
how do extensions work with the approval system?
extensions declare which of their tools are 'mutating' in the manifest. the same autonomy and approval system that gates native actions gates extension actions. a supervised agent calling an extension tool still files a decision for human approval.
is the action registry documented?
yes. the reference docs at /help/reference are auto-generated from the registry. every action's name, description, input schema, method, and mutating flag are rendered directly from the running code — so the docs are always accurate.