API overview

The nima REST API is at https://api.getnima.io. It is the API behind every tool on nima's MCP server: a tool call is one of these routes, made with the caller's own bearer token. Anything an agent can do through nima, a script can do with curl.

One credential covers most of it: a personal API key, sent as Authorization: Bearer. A key belongs to the workspace it was created in and acts as you inside it. Its scopes narrow your own permissions and never widen them, so a key cannot reach what your account cannot.

Make your first API call with a personal API key

Three steps take you from nothing to a signal read: create a key, check it, read something.

export NIMA_API_KEY="nima_…"

curl -s https://api.getnima.io/oauth/userinfo \
  -H "Authorization: Bearer $NIMA_API_KEY"

{
  "sub": "3f8a2c14-9d6b-4c2e-8a77-1b0d5e9f4c21",
  "email": "you@example.com",
  "isOnboarded": true,
  "organizationId": "b71e5c08-2f49-4a6d-9c31-7e5a08d2b4f6",
  "orgRole": "admin"
}

curl -s "https://api.getnima.io/v1/signals?limit=3" \
  -H "Authorization: Bearer $NIMA_API_KEY"

{
  "data": [
    {
      "id": "c04b9a71-5f3e-4d18-9b62-8a7c1e0d5f33",
      "source": "slack",
      "preview": "Bulk export times out on workspaces over 40k rows.",
      "status": "ready",
      "classification": "bug",
      "impact": "high",
      "createdAt": "2026-09-19T09:14:02.401Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 3, "totalItems": 412, "totalPages": 138 }
}

API resource map

Every resource page lists its routes with the scope each one needs and the MCP tool that calls it. Ids are UUIDs, timestamps are ISO 8601 in UTC (a spec's startDate and dueDate are plain YYYY-MM-DD dates), and responses are JSON, with two exceptions: the knowledge graph answers in text/markdown, and an operation's event feed (GET /v1/operations/{id}/events) is a text/event-stream stream.

Pipeline resources

Knowledge resources

Watch resources

Operation resources

Outbound resources

Ingest and admin resources

Session-only API routes

Session-only routes take the signed-in browser session of a workspace member and never a personal API key or OAuth token; called with a key, they answer 403 INSUFFICIENT_PERMISSIONS. They carry no scope because they were built for a signed-in session, and they cover credentials and workspace administration: creating, rotating and revoking API keys (/v1/api-keys), managing webhook senders (/v1/signal-webhooks), reading and changing workspace settings (/organizations/settings), members and invitations, and promoting or editing a beacon (/v1/beacons/{id}/promote, PATCH /v1/beacons/{id}).

No key can create, list, rotate or revoke another key. Two scopes on the map above, operations:write and integrations:write, cannot be put on a key from Settings; an owner or admin mints them in Slack with /nima mcp-key operations or /nima mcp-key integrations. The scopes actions:approve and identities:write cannot be minted by any route today, so the routes that need only them (the action routes and POST /v1/identities/link-me) answer only to a signed-in session. Scopes has the detail.

Everything else the admin panel calls is internal and changes without notice. Treat anything you find in a browser network tab as private.

API error envelope in brief

Every error uses one envelope: statusCode, error, message, timestamp and path, plus details on a 4xx that has any and an incidentId on a 5xx. The X-Request-Id response header carries the same id on every response.

{
  "statusCode": 403,
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "OAuth token scopes do not cover this endpoint",
  "details": { "requiredScopes": ["signals:read"] },
  "timestamp": "2026-09-19T09:14:02.401Z",
  "path": "/v1/signals"
}

Errors lists every code and which are worth retrying, and Rate limits has the tiers.

API stability and paths

API paths are not uniform, and one does not predict the next. These sit under /v1: signals, beacons, events, knowledge, code search, watches and the inbox, scheduled messages, operations, agent compute, webhooks, API keys and the outbound resources. Specs and spec versions are at /documents, spec sections at /prd, workspace settings at /organizations, and the OAuth endpoints at /oauth, with no prefix. Spec dispatch is the mixed case: POST /v1/documents/{id}/dispatch carries the /v1 prefix while the rest of the spec routes do not.

/v1 is a string those routes were written with rather than a version you can negotiate. There is no second version, no version header, and no path whose meaning changes with one. Take every path on this site literally; Conventions lists the base paths.

An OpenAPI 3.1 document covering the key-reachable operations on this site (not the OAuth authorization flow) is published at docs.getnima.io/openapi.json; import it into Postman, Bruno or a client generator.