API reference

Business Summary: The Nimbus API lets your own services, scripts, and apps work with your organization in Nimbus: read and post to workstreams, ask the agent questions, start runs, and react to what happens. Everything you can reach is scoped to one organization and to what its API key allows.

The API is organized around REST. It has predictable resource URLs, accepts JSON request bodies, returns JSON, and uses standard HTTP status codes, authentication, and verbs.

What's live today: Workstreams, messages, the agent, runs, loops, document search, decisions, connections, and webhooks, plus authentication, API keys, errors, versioning, pagination, idempotency, rate limits, request logs, and GET /v1/whoami. Apps can post into rooms as themselves through incoming webhooks and MCP, with interactive Frames. The Nimbus MCP server (https://mcp.gonimbus.ai) lets an API key drive tasks and rooms from an MCP client. See MCP.

Base URL

Send every request to the API origin for your organization's data region, followed by /v1:

Data region	Base URL
United States	`https://api.gonimbus.ai/v1`
European Union	`https://api-eu.gonimbus.ai/v1`

Not sure which region your organization is in? Call GET /v1/whoami. Its data_region field tells you, and the Developers page in Nimbus shows the base URL for your organization.

Your first request

Create a key under Developers in Nimbus (you need to be an organization admin; see API keys), then check it works:

::: code-group

curl https://api.gonimbus.ai/v1/whoami \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch('https://api.gonimbus.ai/v1/whoami', {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const whoami = await response.json()
console.log(whoami.organization.name, whoami.api_key.scopes)

import os
import requests

response = requests.get(
    "https://api.gonimbus.ai/v1/whoami",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
whoami = response.json()
print(whoami["organization"]["name"], whoami["api_key"]["scopes"])

:::

{
  "object": "whoami",
  "organization": { "id": "acme", "name": "Acme Corp" },
  "api_key": {
    "id": "key_7fQ2mN4pR8sT1vW3xY5zA1bC",
    "object": "api_key",
    "name": "Production backend",
    "kind": "secret",
    "scopes": ["*"],
    "last4": "x9Qa",
    "expires_at": null
  },
  "data_region": "us",
  "api_version": "2026-09-25"
}

Pick a language once in any example and the whole reference switches to it.

Conventions

Convention	What it means
JSON everywhere	Send `Content-Type: application/json` with a body; every response, including errors, is JSON.
snake_case fields	Response fields use `snake_case`, such as `data_region` and `expires_at`.
Timestamps	Unix seconds, in UTC. `null` means "not set", such as a key that never expires.
Object IDs	Prefixed strings such as `key_…` and `req_…`. Treat them as opaque; don't parse them.
`object` field	Every object says what it is, such as `"object": "api_key"`, so you can dispatch on it.
Request IDs	Every response has a `Request-Id` header. Quote it to support. See Request IDs and logs.
Versions	Pin a version with the `Nimbus-Version` header. See Versioning.

Start here

Guide	Read it when
Authentication	You're sending your first request, or a request is being refused with `401`.
API keys	You're creating, restricting, rolling, or revoking keys.
Errors	You're handling failures, or looking up an error `code`.
Versioning	You're deploying code that has to keep working as the API changes.
Rate limits	You're sending many requests, or got a `429`.
Request IDs and logs	You're debugging a request or watching traffic on the Developers page.
Retrieve the current key	You want to confirm which key and organization a request runs as.
Pagination	You're reading a list longer than one page.
Idempotent requests	You're retrying requests that create things, and must not create them twice.

Endpoints

Resource	What you can do
Workstreams	List, create, rename, archive, and delete workstreams.
Messages	Read a workstream's room, post and edit messages, and reply in threads.
Agent	Ask a workstream's agent a question, and poll or stream its answer.
Runs	Track runs and fetch their reports.
Loops	List loops and their executions, and run a loop now.
Documents	Search the Company Wiki and connected documents by meaning.
Decisions	List the decisions recorded in a workstream.
Connections	See which apps are connected and whether they work.
Webhooks	Get events sent to your server, and list recent events.
Apps	Create Apps, install them on workstreams and Conflux rooms, and rotate or revoke their credentials.

Building Apps

Guide	Read it when
Apps	You want a tool to post into a room under its own name and icon.
Incoming webhooks	You want to post from CI, a script, or any system with one signed HTTPS request.
Frames	You want structured, interactive messages with fields, tables, buttons, and menus.
MCP	You want an MCP client to keep tasks, ask the agent, and post in rooms, or to act in one room as your App.

OpenAPI document

The whole API is described in an OpenAPI 3.1 document, served without authentication:

GET https://api.gonimbus.ai/v1/openapi.json

Use it to generate a client in your language, import the API into a tool such as Postman, or check the exact schema of any request and response. It lists every endpoint with its parameters, the scope it needs, and which endpoints accept an Idempotency-Key.

How this fits in Nimbus

The API acts for your organization, not for a person. A key belongs to the organization that created it, and a request made with it is recorded against that key on the Developers page, in the request log, and every key change (created, revealed, rolled, revoked) is written to the organization's audit log. Organization admins manage keys; members don't see the Developers page.

FAQ

Is there an SDK?

Not yet. The API is plain HTTPS and JSON, so any HTTP client works; the examples here use fetch and Python's requests. Official TypeScript and Python clients are planned and will appear in these examples when they ship.

Can I call the API from a browser?

The API sends CORS headers, so a browser can call it, but don't put a secret key in code that runs on someone else's device. Anyone who opens the page can read it. Call the API from your server instead.

Does the API cost anything?

Requests aren't metered on their own today. Work they start, such as agent answers and runs, uses NTUs the same way it would from the app. See What are NTUs.

What happens to my data region if I use the wrong base URL?

Your data stays in its region either way: the API looks up the organization from the key and reads and writes that organization's regional database. Using your region's base URL keeps the request itself in that region, too.

Where do I report a problem with the API?

Contact support and include the Request-Id of a failing request. It lets us find exactly what happened.