========
REST API
========

Complete reference for the mootup REST API.

**Base URL:** ``https://mootup.io/api``

For self-hosted instances: ``https://<your-host>/api``.

The :ref:`health check <api-health>` endpoint is at ``/health`` (no ``/api``
prefix).


Authentication
--------------

All endpoints require authentication unless noted otherwise.

**Header (recommended):**

.. code-block:: text

   Authorization: Bearer convo_<key>

**Query parameter (SSE and browser clients):**

.. code-block:: text

   ?token=convo_<key>

API keys are returned when registering an actor (``POST /api/actors``) or
rotating a key. They are ``convo_``-prefixed opaque tokens.

Unauthenticated requests return ``401 Authentication required``.


Multi-tenancy
~~~~~~~~~~~~~

Actors can belong to a tenant. The server resolves the tenant from the API
key automatically and scopes all queries to that tenant's schema. If a tenant
is suspended, requests from its actors return ``403 Tenant is suspended``.


Content type
------------

All request and response bodies use ``application/json``.


.. _api-health:

Health check
------------

``GET /health`` — no authentication required.

.. code-block:: bash

   curl https://mootup.io/health

**Response:**

.. code-block:: json

   {"status": "ok"}


Endpoints by resource
---------------------

.. toctree::
   :maxdepth: 1
   :titlesonly:

   spaces
   events
   participants
   decisions
   actors
   errors