Workspace settings

Read and change workspace-level settings, including the switches for watches, outbound actions and chat fact capture.

Workspace settings are a small set of workspace-wide switches and values: the workspace description, your own email domains, the two switches that let nima send watch notifications and write into your tools, and the outbound-dispatch knobs. Two routes read and change them. Both are session routes: they answer a signed-in person in the app, not an API key and not an MCP token.

Off until a workspace owner or admin turns it on. The switches triggersEnabled and dispatchEnabled both default to false, and the only control is PATCH /organizations/settings called with a signed-in owner or admin session, or ask the nima team. The admin panel has no control for them, and there is no API key or MCP route.

Workspace settings routes

The workspace settings routes are GET and PATCH /organizations/settings.

Method	Path	Who can call it	MCP tool
`GET`	`/organizations/settings`	any member, signed-in session	none
`PATCH`	`/organizations/settings`	owner or admin, signed-in session	none

Paths are relative to https://api.getnima.io and carry no /v1 prefix. Send the session access token as Authorization: Bearer <session token>. A key from Settings, API keys and an MCP token are refused with 403 and the message This endpoint does not accept OAuth access tokens. See Authentication for the two kinds of credential.

Read workspace settings

GET/organizations/settings

app session only

Returns the settings of the workspace your session is in. Any member can read them. Every field has a default, so a workspace that never wrote a setting still gets a complete object.

beaconMinClusterSizeinteger

2 or 3. Stored, but it no longer changes how beacons form. See Grouping setting.

descriptionstring | null

What your company builds. null until someone writes it.

internalDomainsstring[]

Your own email domains. Defaults to [].

triggersEnabledboolean

Whether watches can fire for this workspace. Defaults to false.

dispatchEnabledboolean

Whether nima may write into your integrations. Defaults to false.

chatFactCaptureEnabledboolean

Defaults to false. The feature it gates is not available yet.

dispatchobject

mentionsEnabled (boolean, default false), dailyUsdCap (number, default 5) and internalProjects (a list of provider, projectKey, assertedByUserId and assertedAt, default []).

The response also carries internal rollout fields that only the nima team sets. Ignore them.

Response

{
  "beaconMinClusterSize": 2,
  "description": "Project tracking for construction teams.",
  "internalDomains": ["acme.com"],
  "triggersEnabled": false,
  "dispatchEnabled": false,
  "chatFactCaptureEnabled": false,
  "dispatch": {
    "internalProjects": [],
    "mentionsEnabled": false,
    "dailyUsdCap": 5
  }
}

Change workspace settings

PATCH/organizations/settings

app session only

Changes any subset of the settings and returns the full settings object. Only an owner or admin can call it: a member gets 403. Fields you leave out keep their value. The body is validated before anything is written, so a bad field changes nothing.

beaconMinClusterSizeinteger

2 to 3. Accepted and stored, with no effect on grouping.

descriptionstring | null

At most 1000 characters. Trimmed. null (or an empty string) clears it.

internalDomainsstring[]

At most 20 entries, each at most 253 characters. Replaces the whole list; [] clears it. Each entry is normalized to a bare lowercase domain: a scheme, a leading www. or @, and any path are stripped, and duplicates collapse. An entry that is not a domain, such as acme, fails the request with 400.

triggersEnabledboolean

Turns watch notifications on or off for the workspace. See Watches and reminders.

dispatchEnabledboolean

Turns outbound actions on or off for the workspace. See Outbound actions.

chatFactCaptureEnabledboolean

Accepted and stored. The feature it gates is not available yet, so setting it changes nothing today.

dispatchobject

Outbound-dispatch knobs. Fields you omit keep their value. Its fields are listed under Dispatch object.

Dispatch object fields

The dispatch object sets three outbound-action knobs. Each field is optional. The write is audited: nima records one policy_changed event with the keys and values that changed, and writing values the workspace already has records nothing.

mentionsEnabledboolean

Whether automated messages may render real @mentions. Off, nima writes plain display names and pings nobody.

internalProjectsobject[]

Tracker projects you assert are internal-only, as provider (at most 40 characters, for example jira) and projectKey (at most 80 characters, no whitespace, compared case-insensitively). At most 100 entries. This replaces the stored list, and [] clears it, so send every project you want to keep. Repeated entries collapse.

dailyUsdCapnumber

0 to 1000, rounded to cents. The most nima spends per UTC day on agent runs that watches and rules start for the workspace. Once today's spend reaches the cap, further agent runs are refused until midnight UTC. 0 stops them.

Sending dispatch needs a signed-in person, which a session always is. Owners and admins can both write it. dailyUsdCap and internalProjects change what the workspace's outbound actions do: see Action policies for the per-tool approval levels that sit beside them.

Grouping setting has no effect

beaconMinClusterSize is stored and echoed back, and Settings, Grouping in the admin panel still shows it, but it no longer affects how signals group into beacons. Do not treat it as a control.

Settings errors

Status	Cause
`400`	A field has the wrong type or is out of range: `beaconMinClusterSize` outside 2 to 3, `description` over 1000 characters, more than 20 `internalDomains` or an entry that is not a domain, more than 100 `internalProjects`, an `internalProjects` entry without a provider or project key, or `dailyUsdCap` outside 0 to 1000.
`401`	No session token, or an expired one.
`403`	The caller is a member and not an owner or admin, the session has no workspace, or the credential is an API key or MCP token.

Error bodies follow the shape in Errors.

Turn on watches and outbound actions

curl -X PATCH https://api.getnima.io/organizations/settings \
  -H "Authorization: Bearer <session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "triggersEnabled": true,
    "dispatchEnabled": true
  }'

Set your domains and dispatch knobs

curl -X PATCH https://api.getnima.io/organizations/settings \
  -H "Authorization: Bearer <session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "internalDomains": ["acme.com", "acme.io"],
    "dispatch": {
      "mentionsEnabled": true,
      "dailyUsdCap": 10,
      "internalProjects": [
        { "provider": "jira", "projectKey": "ENG" }
      ]
    }
  }'

Response

{
  "beaconMinClusterSize": 2,
  "description": null,
  "internalDomains": ["acme.com", "acme.io"],
  "triggersEnabled": true,
  "dispatchEnabled": true,
  "chatFactCaptureEnabled": false,
  "dispatch": {
    "internalProjects": [
      {
        "provider": "jira",
        "projectKey": "ENG",
        "assertedByUserId": "<user id>",
        "assertedAt": "2026-09-30T09:00:00.000Z"
      }
    ],
    "mentionsEnabled": true,
    "dailyUsdCap": 10
  }
}

Two switches for watches and outbound actions

Watches and outbound actions each need two switches, and the workspace setting is only the second one. The platform side is on in production. The workspace side, triggersEnabled for watches and dispatchEnabled for outbound actions, defaults to false, so a workspace stays quiet until an owner or admin sets it. Turning either setting off later stops that feature for the workspace: watches stop firing, and an outbound action already approved but not yet sent is refused at send time.

Watches that a person creates while triggersEnabled is false are rejected with 409, as described in Watches. Organization-wide ticket rules need both settings on.

Where to change settings without the API

The admin panel has a Settings page with General, Members, API keys, Grouping, Billing, Usage and Account tabs. None of them edits the switches on this page. Details are in Admin panel and Availability. For a workspace where nobody can call the route, ask the nima team.