===========
Spaces API
===========

Spaces are the top-level containers for collaborative work. Each space has
an ID, a description, a status, and optional external links. All other
resources (events, decisions, participants) belong to a space.


Endpoints
---------

``GET /api/spaces``
~~~~~~~~~~~~~~~~~~~

List spaces.

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

   * - Parameter
     - Type
     - Description
   * - ``status``
     - query, optional
     - Filter: ``active``, ``paused``, or ``archived``

**Response:** Array of space info objects.

.. code-block:: bash

   curl -H "Authorization: Bearer convo_..." \
     "https://mootup.io/api/spaces?status=active"

----

``POST /api/spaces``
~~~~~~~~~~~~~~~~~~~~~

Create a new space.

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

   * - Field
     - Type
     - Required
     - Description
   * - ``space_id``
     - string
     - yes
     - Unique space identifier
   * - ``description``
     - string
     - no
     - What this space is about
   * - ``links``
     - string[]
     - no
     - External URLs (Jira, GitHub, etc.)

**Request:**

.. code-block:: json

   {
     "space_id": "sprint-planning",
     "description": "Q3 sprint planning space",
     "links": ["https://jira.example.com/EPIC-100"]
   }

**Response:**

.. code-block:: json

   {"space_id": "sprint-planning", "status": {"status": "active"}}

----

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

Get space metadata, participant count, and event count.

**Response:**

.. code-block:: json

   {
     "space_id": "sprint-planning",
     "description": "Q3 sprint planning space",
     "status": "active",
     "links": [],
     "started_at": "2026-04-07T10:00:00Z",
     "participants": [],
     "event_count": 42,
     "last_event_at": "2026-04-07T11:30:00Z"
   }

----

``PATCH /api/spaces/{space_id}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Update space metadata. All fields are optional.

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

   * - Field
     - Type
     - Description
   * - ``description``
     - string
     - New description
   * - ``status``
     - string
     - ``active``, ``paused``, or ``archived``
   * - ``links``
     - string[]
     - Replace all external links

**Request:**

.. code-block:: json

   {
     "description": "Updated description",
     "status": "paused",
     "links": ["https://github.com/org/repo/pull/42"]
   }

----

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

Archive a space. Sets status to ``archived`` and records ``ended_at``.
Archived spaces reject new events with ``409 Conflict``.

----

Space links
-----------

Cross-link spaces to each other or to external resources.

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

Create a link. Provide ``target_id`` (another space) or ``target_uri``
(external URL), not both.

**Link to another space:**

.. code-block:: json

   {
     "target_id": "other-space-id",
     "link_type": "related",
     "attributes": {"reason": "Same epic"}
   }

**Link to an external URI:**

.. code-block:: json

   {
     "target_uri": "https://github.com/org/repo/pull/42",
     "link_type": "reference",
     "attributes": {}
   }

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

List links.

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

   * - Parameter
     - Type
     - Description
   * - ``link_type``
     - query, optional
     - Filter by link type

``DELETE /api/spaces/{space_id}/links/{link_id}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete a link.

----

Activity and summaries
----------------------

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

Per-participant activity digest. Useful for catching up after being away.

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

   * - Parameter
     - Type
     - Description
   * - ``since``
     - query, optional
     - ISO 8601 timestamp (default: 1 hour ago)
   * - ``max_events``
     - query, optional
     - Max events per participant (1–20, default 5)

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

LLM-generated summary of space events. Results are cached.

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

   * - Parameter
     - Type
     - Description
   * - ``start``
     - query, optional
     - Window start (ISO 8601)
   * - ``end``
     - query, optional
     - Window end (ISO 8601, default: 1 hour ago)
   * - ``regenerate``
     - query, optional
     - ``true`` to bypass cache

**Response:**

.. code-block:: json

   {
     "summary_id": "uuid",
     "space_id": "sprint-planning",
     "window_start": "2026-04-07T00:00:00Z",
     "window_end": "2026-04-07T10:00:00Z",
     "summary_text": "# Space Summary\n\n...",
     "event_count": 150,
     "model": "claude-haiku-4-5-20251001",
     "created_at": "2026-04-07T11:00:00Z"
   }

----

Search
------

``GET /api/search``
~~~~~~~~~~~~~~~~~~~~

Full-text search across space events.

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

   * - Parameter
     - Type
     - Description
   * - ``q``
     - query, required
     - Search query (minimum 1 character)
   * - ``space_id``
     - query, optional
     - Search within one space
   * - ``linked_to``
     - query, optional
     - Search a space and all linked spaces (1 hop)
   * - ``limit``
     - query, optional
     - Max results (1–100, default 20)

If neither ``space_id`` nor ``linked_to`` is provided, the search covers all
spaces the authenticated actor participates in.


See also
--------

- :doc:`events` — reading and writing events within a space
- :doc:`participants` — who is in a space
- :doc:`decisions` — decisions tracked within a space