Skip to content

Use our API ​

The REST API is the platform's raw surface: every capability, exposed as its endpoints as-is. The SDKs are a thin layer over these same endpoints, so nothing you read here falls outside what they already call.

When it's your path ​

This is your path if your stack has no official SDK, or if you need one endpoint the SDK does not wrap yet. If you keep picturing yourself writing the wrapper by hand, check Use the SDK first: it covers the whole API and already paginates and translates errors for you.

Connecting ​

You need one thing: a secret key sk_. An OWNER or ADMIN of your company issues it from the dashboard (API Keys) and it stays bound to your company; its full value is shown only at creation — the platform cannot recover it afterwards. Store it in the NIMOBASE_SECRET_KEY variable.

Nothing else. The client handles the URL: there is no base URL to configure. If you call with curl and need your environment's host, see Environments.

Using it ​

First request: list the active companies in your tenant (Companies). YOUR_HOST is the host of your environment — see Environments — and v1 is the contract version: routes in this documentation are shown without the prefix, so when you call by hand you add it yourself.

bash
curl "https://YOUR_HOST/v1/companies?page=1&limit=20" \
  -H "X-API-Key: $NIMOBASE_SECRET_KEY"

You don't get a plain array: every listing arrives in an envelope with the count and the page you asked for.

json
{
  "data": [/* the companies on this page */],
  "total": 12,
  "page": 1,
  "limit": 20
}
  • data — the instances on the requested page.
  • total — the real count for the whole listing.
  • page and limit — the page and the size actually applied.

An out-of-range page is not an error: data comes back empty and total still reflects the real count.

Pagination — every listing accepts ?page (default 1) and ?limit (default 20, maximum 100). The 100-instances-per-request cap is the API's own.

Errors — the HTTP status says what failed, and the body message spells it out:

StatusWhen it appears
400The input can't be processed: an invalid field, or an entity that only has a draft so far.
401No valid credential — the key doesn't exist or was revoked (Invalid API key), or it reached its expiry date (API key has expired).
403The key is valid but its operation list doesn't include what you called (Insufficient authorization for this operation), or the plan lacks the requested feature.
404The resource doesn't exist — a cross-read into another tenant also answers 404, without leaking that it exists.
409Conflict with a business rule: a plan limit reached, a rotation attempted on an already-revoked key.

A 401 on a request that otherwise looks right usually means the key was rotated: rotation invalidates the previous secret immediately, with no grace period.

Next steps ​

  • Environments — Production and Sandbox, and how you pick one.
  • Modules — every capability's endpoints, with their roles and limits.
  • Use the SDK — the same API, already wrapped.