Decisions

Decisions

Reference article: Part of the API reference. For decisions in the app, see People, teams, and decisions.

As work happens in a workstream, Nimbus records the decisions made along the way: what was decided, why, by whom, and whether a later decision replaced it. This endpoint lists a workstream's decisions, so you can mirror them into a compliance system, a changelog, or a weekly digest.

You can only list decisions in workstreams the key can reach. See Which workstreams a key can reach.

The Decision object

{
  "id": "a7c2e9f4-1b5d-4a8e-9c3f-6e0b2d8a4f71",
  "object": "decision",
  "workstream": "3f6c2a1e-8b4d-4e2f-9a7c-5d1b0e6f2a94",
  "run": "c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13",
  "category": "pricing",
  "summary": "Hold list prices for existing customers until 1 January.",
  "reasoning": "Two of three suppliers' increases take effect in November; absorbing them for one quarter keeps renewals on track.",
  "status": "approved",
  "decided_by": { "type": "human", "id": "d4e8b1a6-2c7f-4e9b-8a3d-5f0c1b7e2a94" },
  "superseded_by": null,
  "decided_at": 1758790500,
  "created": 1758790022
}
Field Type Description
id string The decision's ID.
object string Always decision.
workstream string or null The ID of the workstream it was made in.
run string or null The ID of the run it was made in, if any.
category string What kind of decision it is.
summary string The decision, in a sentence.
reasoning string or null Why it was made.
status string proposed, approved, rejected, or superseded. See Statuses.
decided_by object Who made it: type and id. See Deciders.
superseded_by string or null The ID of the decision that replaced this one, if any.
decided_at integer or null When it was decided, in Unix seconds, when recorded.
created integer When it was recorded, in Unix seconds.

Statuses {#statuses}

Status Meaning
proposed Put forward, not yet approved or rejected.
approved Accepted.
rejected Turned down.
superseded Replaced by a later decision, named in superseded_by.

Deciders {#deciders}

decided_by.type says what kind of participant made the decision. Either field can be null when it isn't recorded.

Type Meaning
human A person.
agent A Nimbus agent.
integration A connected system.
system Nimbus itself.

List decisions

Returns a workstream's decisions, newest first. Superseded decisions are left out unless you ask for them.

GET /v1/workstreams/{workstream}/decisions

Scope: decisions:read

Parameter In Type Description
workstream path string The workstream's id or slug.
limit query integer, optional How many objects to return, 1–100. Default 20.
cursor query string, optional The next_cursor from the previous page. See Pagination.
run query string, optional Only decisions made in this run.
include_superseded query string, optional true to include decisions that were later superseded. Default false.

::: code-group

curl "https://api.gonimbus.ai/v1/workstreams/q4-pricing-review/decisions?include_superseded=true" \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch(
  'https://api.gonimbus.ai/v1/workstreams/q4-pricing-review/decisions?include_superseded=true',
  { headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` } },
)
const { data: decisions } = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/workstreams/q4-pricing-review/decisions",
    params={"include_superseded": "true"},
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
decisions = response.json()["data"]

:::

Returns a list object of Decision objects.

Note: include_superseded takes the strings true and false. Other values, such as 1 or yes, fail with 400 parameter_invalid.

Example scenario

A compliance team keeps an external register of every pricing decision. A small job subscribes a webhook endpoint to decision.recorded, and when an event arrives, lists the workstream's decisions with include_superseded=true to pick up the full record, including reasoning and whether an earlier decision was replaced. The register always matches what was decided in Nimbus, with who decided it and why.

FAQ

How do I hear about new decisions without polling?

Subscribe a webhook endpoint to decision.recorded. The event carries the decision's id, workstream, run, category, summary, and status; list the workstream's decisions for the rest.

Can I record or approve a decision through the API?

No. Decisions are recorded as work happens in Nimbus, and approved or rejected there. See Human in the loop.

Why don't I see a decision that was replaced?

Superseded decisions are left out by default. Pass include_superseded=true.

Can I list decisions across all workstreams at once?

No. Decisions are listed per workstream. Page through List workstreams and list each one's decisions.

What does decided_by.id refer to?

The person, agent, integration, or system that made the decision, as Nimbus recorded it. Treat it as an opaque identifier; it isn't always a user ID.