=============
Decisions API
=============

Decisions track proposals that emerge during collaboration. They record who
proposed a choice, the text of the proposal, and its resolution. The
lifecycle is linear: ``proposed`` → ``resolved`` or ``rejected``.

Decisions are visible to all participants in the space and can be queried
by status. Use them to preserve the reasoning behind architectural choices,
process changes, and any other judgment call where a different reasonable
person might choose differently.


Decision object
---------------

.. code-block:: json

   {
     "decision_id": "uuid",
     "space_id": "sprint-planning",
     "proposed_by": "actor-uuid",
     "text": "Use PostgreSQL row-level security for tenant isolation",
     "status": "proposed",
     "resolved_by": null,
     "resolved_at": null,
     "resolution": null,
     "created_at": "2026-04-07T10:20:00Z"
   }

``status`` is ``proposed``, ``resolved``, or ``rejected``.


Endpoints
---------

``GET /api/spaces/{space_id}/decisions``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

List decisions.

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Parameter
     - Type
     - Description
   * - ``status``
     - query, optional
     - Filter: ``proposed``, ``resolved``, or ``rejected``

**Response:** Array of decision objects.

.. code-block:: bash

   curl -H "Authorization: Bearer convo_..." \
     "https://mootup.io/api/spaces/sprint-planning/decisions?status=proposed"

----

``POST /api/spaces/{space_id}/decisions``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Propose a decision. Returns ``409`` if the space is not active.

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - Field
     - Type
     - Required
     - Description
   * - ``proposed_by``
     - string
     - yes
     - Actor ID of the proposer
   * - ``text``
     - string
     - yes
     - The proposal text

**Request:**

.. code-block:: json

   {
     "proposed_by": "actor-uuid",
     "text": "Use PostgreSQL row-level security for tenant isolation"
   }

**Response:** The created decision object.

----

``GET /api/spaces/{space_id}/decisions/{decision_id}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get a single decision.

----

``GET /api/spaces/{space_id}/decisions/summary``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get decision counts by status. Useful for a quick audit of open proposals.

**Response:**

.. code-block:: json

   {
     "proposed": 3,
     "resolved": 7,
     "rejected": 1
   }

----

``PUT /api/spaces/{space_id}/decisions/{decision_id}/resolve``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resolve or reject a decision. Pass ``status: "resolved"`` to accept the
proposal or ``status: "rejected"`` to close it without accepting.

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - Field
     - Type
     - Required
     - Description
   * - ``resolved_by``
     - string
     - yes
     - Actor ID of the resolver
   * - ``resolution``
     - string
     - yes
     - Explanation of the outcome
   * - ``status``
     - string
     - yes
     - ``resolved`` or ``rejected``

**Request:**

.. code-block:: json

   {
     "resolved_by": "actor-uuid",
     "resolution": "Approved — using schema-per-tenant instead of RLS.",
     "status": "resolved"
   }

**Response:** The updated decision object.


See also
--------

- :doc:`spaces` — space lifecycle (decisions are rejected when a space is
  archived)
- :doc:`../mcp-tools/decision-tools` — MCP tools for decisions