Nimbio API — Developer Reference & Clients

What is the Nimbio API?

The Nimbio API is a REST API for programmatic access to Nimbio's cellular smart-gate access control platform — opening gate latches, granting and revoking community member keys, sending community messages, and reading access logs, all authenticated with a scoped API key over HTTPS. The Nimbio API is served from api.nimbio.com and is documented with an interactive OpenAPI reference, downloadable Postman and Bruno collections, and an official Python SDK.

Quickstart

How do I make my first API call?

Every endpoint takes a bearer token. Use a nimbio_test_… key to explore safely — it runs the full pipeline (auth, rate limit, scope, validation) but never fires a gate or mutates data. Switch to nimbio_live_… for real side effects.

# Who am I? Works with any key.
curl https://api.nimbio.com/v1/me \
  -H "Authorization: Bearer nimbio_test_…"

# Open a community latch (community-scoped key)
curl -X POST https://api.nimbio.com/v1/community/latches/<id>/open \
  -H "Authorization: Bearer nimbio_live_…"

Good to know

Keys are created in the Nimbio admin / community portal. The raw token is shown once.
Community endpoints (/v1/community/*) need a community-scoped key from a community manager.
Rate limits apply per-minute and per-month; a breach returns 429 with a Retry-After header. Limit headers are returned on every response.
Errors use a uniform envelope with a request_id for support.

Reference & SDKs

Where can I find the API reference?

Interactive references generated from the live OpenAPI schema, plus official clients for Python and TypeScript/JavaScript and an MCP server for AI assistants.

API Reference

The full reference, grouped into Account and Community APIs. Browse endpoints, schemas, and examples in one place.

Open /reference →

Account API

Build on your own account: read your keys and their latches, and open your latches. Uses an account API key.

Account endpoints →

Community API

Build for a community you manage: gate status, members, member keys, opens, and access logs. Uses a community API key.

Community endpoints →

Swagger UI

Interactive reference. Click Authorize, paste a key, and call endpoints live from the browser.

Open /docs →

ReDoc

A clean, readable three-panel view of the same reference — good for skimming the whole API.

Open /redoc →

Python SDK

Official Python client, synchronous and asynchronous. Install with pip install nimbio-community-api.

View on PyPI →

TypeScript SDK

Official TypeScript/JavaScript client — zero dependencies, runs in Node, the browser, Deno, Bun, and edge. Install with npm install @nimbio/community-api.

View on npm →

MCP Server

Official Model Context Protocol server — connect Claude, ChatGPT, Cursor or any MCP client and run your community in plain language. Read-only by default. Run with npx -y @nimbio/mcp-server.

View on npm →

AI assistants

Can I run my community from an AI assistant?

Yes — Nimbio publishes an official Model Context Protocol server. Connect Claude, ChatGPT, Cursor or any MCP client and work in plain language instead of code. It is built on the TypeScript SDK, so it reaches the same API surface.

How do I set it up?

Add this to your assistant’s MCP configuration. There is nothing to clone and nothing to build.

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "nimbio": {
      "command": "npx",
      "args": ["-y", "@nimbio/mcp-server"],
      "env": {
        "NIMBIO_API_KEY": "nimbio_test_…"
      }
    }
  }
}

Start with a test key. Test keys run the full pipeline — authentication, rate limiting, permissions, validation — and then simulate, so no gate opens and nobody is messaged. Everything below is safe to explore with one.

What can I ask it?

“Which gates are offline right now?”
“Who opened the north gate after midnight last week?”
“Approve the pending member and give them a resident key.”
“Issue a guest link for a plumber visiting Tuesday afternoon.”
“Hold the delivery gate open 9am to 11am next Monday.”
“Why didn't my webhook receive last night's open?”

Coverage spans gates and hold opens, members and keys, guest links, access codes and GuestView Entry, the access and audit logs, community settings, hardware, and webhooks.

Is it safe?

The cautious answer is the default in every case.

Reads by default

A fresh install can see the whole community and change nothing. Write access is a deliberate step.

Live keys need a second opt-in

A live key registers zero write tools without NIMBIO_MCP_ALLOW_LIVE, so a hurried install can only look.

Irreversible actions ask a person

Opening a gate, holding one open, revoking a guest link, removing a home, replaying webhooks, switching access-code mode and messaging every member all stop and confirm first. The assistant cannot answer that prompt for you.

Guest links stay secret

A guest link opens your gate for anyone holding it, so its token and URL are redacted unless you explicitly ask for them.

Every answer says which world it is in

Results are labelled TEST MODE or LIVE and name the host they came from.

How do I configure it?

Everything is set through environment variables in your MCP configuration.

NIMBIO_API_KEY  (required)
  Your API key. Start with a test key (nimbio_test_…) — it runs the full pipeline and then simulates, so no gate opens.
NIMBIO_MCP_MODE  (read-only)
  read-only, write, or unrestricted. The default lets the assistant read everything and change nothing.
NIMBIO_MCP_ALLOW_LIVE  (unset)
  Required before a live key may register write tools. Without it, a live key gets read tools only.
NIMBIO_ENV  (prod)
  prod or dev. Note the default is prod — set it explicitly when testing.
NIMBIO_MCP_ALL_TOOLS  (unset)
  Register every tool regardless of what the key's permissions allow. Diagnostic; rarely wanted.

Troubleshooting

No write tools? That is the default. Set NIMBIO_MCP_MODE=write, and for a live key also NIMBIO_MCP_ALLOW_LIVE.
Fewer tools than expected? The list is filtered to what your key is permitted to do, so the assistant never picks a tool that would fail. Ask it “what can you do?” to see the reason.
Talking to the wrong system? NIMBIO_ENV defaults to prod. Every result names the host it came from, so check there first.
It refuses to start. It exits with the reason on stderr — most often a missing NIMBIO_API_KEY.

Where do I get the details?

The repository README and CHANGELOG carry the full tool list, the confirmation behaviour, and the release history.

View on npm → Source on GitHub →

Clients & tooling

What API clients can I download?

Kept in sync with the live API. Import a collection, or codegen straight from the OpenAPI spec.

OpenAPI specification

The full machine-readable OpenAPI 3 spec — import into any client or codegen tool.

View /openapi.json →

Postman collection

Ready-to-run Postman collection with every endpoint, plus dev / prod / local environments.

Download collection →

Prod environment →Dev environment →Local environment →

Bruno collection

The same requests as a Bruno collection (open-source API client) — download and open the folder.

Download .zip →

FAQ

Frequently asked questions

Does the Nimbio API have a sandbox or test mode?

Yes. Every endpoint accepts test keys (prefixed nimbio_test_) that run the full request pipeline — authentication, rate limiting, scope checks, and validation — but never fire a gate or mutate data; writes come back simulated. Switch to a live key (nimbio_live_) only when you want real side effects.

What SDKs are available for the Nimbio API?

Two official clients with matching endpoint coverage: a Python client (nimbio-community-api on PyPI, pip install nimbio-community-api) with synchronous and asynchronous interfaces, and a TypeScript/JavaScript client (@nimbio/community-api on npm) that runs in Node, the browser, Deno, Bun, and edge runtimes. Every endpoint is also reachable directly over HTTPS, and importable Postman and Bruno collections are available on this page. For AI assistants there is also an official MCP server, @nimbio/mcp-server on npm.

Can I use Nimbio with an AI assistant like Claude or ChatGPT?

Yes. Nimbio publishes an official Model Context Protocol (MCP) server, @nimbio/mcp-server on npm, which connects any MCP client — Claude, ChatGPT, Cursor and others — to a community you manage. Run it with npx -y @nimbio/mcp-server and an API key, and you can ask for gate status, access-log history, member and key changes, guest links and hold opens in plain language. It is built on the TypeScript SDK, so it covers the same API surface.

Is it safe to give an AI assistant access to my gates?

The MCP server is built so the cautious answer is the default. It starts in read-only mode, so a fresh install can read everything and change nothing. A live key registers no write tools at all unless you set NIMBIO_MCP_ALLOW_LIVE, so the worst outcome of a hurried setup is an assistant that can only look. Anything irreversible — opening a gate, holding one open, revoking a guest link, removing a home, messaging every member — stops and asks a person first, and the assistant cannot answer that prompt on your behalf. Guest-link tokens are redacted unless you ask for them, and every result is labelled TEST MODE or LIVE. Start with a test key, which simulates every write.

Does the Nimbio API have rate limits?

Yes. Requests are limited per minute and per month, with separate counters for test and live keys. When you exceed a limit the API returns HTTP 429 with a Retry-After header telling you how long to wait, and the current usage is returned on every response in X-RateLimit headers.

Do I need a live API key just to read the docs?

No. The interactive documentation at /docs and /redoc, and the raw OpenAPI specification at /openapi.json, are public — you can browse the entire API reference without a key. An API key is only needed to actually call an endpoint.