Swagger API Documentation
=========================

TouchPoint provides an interactive API documentation site powered by `Swagger UI <https://swagger.io/tools/swagger-ui/>`_. This site lets you explore all available API endpoints, review request and response formats, and test calls directly from your browser.

**API Documentation Site:** `https://api.tpsdb.com/api/swagger/ui <https://api.tpsdb.com/api/swagger/ui>`_

What You Can Do
---------------

- Browse all available REST API endpoints organized by category
- View required and optional parameters for each endpoint
- Inspect example request and response schemas
- Execute live API calls directly from the browser using your credentials

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

Most endpoints require authentication. The Swagger UI supports authenticating with a **Personal Access Token (PAT)**, which is the recommended method.

.. seealso::
    :doc:`PersonalAccessTokens`

To authenticate in Swagger UI:

1. Generate a PAT using the ``api/v1/Account/CreateUserAccessToken`` endpoint (or use an existing one).
2. Click the **Authorize** button at the top right of the Swagger UI page.
3. Enter your token in the format ``PAT <your-token>`` and click **Authorize**.

Once authorized, subsequent calls made from the Swagger UI will include your token automatically.

.. note::
    The Swagger UI connects to the live API. Any write operations (POST, PUT, DELETE) performed through the UI will affect real data.

The CmsHost Header
------------------

Because the Swagger UI is hosted at the shared ``api.tpsdb.com`` domain rather than your church's own URL, most endpoints require a ``CmsHost`` header so that the API knows which church database to direct the request to.

Set the ``CmsHost`` header to your church's TouchPoint subdomain — for example::

    CmsHost: mychurch

You can provide this header in two ways:

- **Per-request** — Add it manually in the request headers panel when expanding an endpoint in Swagger UI.
- **Globally via Authorize** — Click the **Authorize** button, find the ``CmsHost`` field, enter your hostname, and click **Authorize**. This applies the header to all subsequent requests automatically, alongside your PAT.

.. tip::
    When building a real integration that calls your church's URL directly (e.g., ``https://mychurch.tpsdb.com/api/v1/...``), the ``CmsHost`` header is **not needed** — the hostname is already embedded in the URL itself. The header is only required when routing requests through the shared Swagger host.

|
|

+--------------------+------------------+
| **Latest Update**  |  **04/21/2026**  |
+--------------------+------------------+

Initial documentation for Swagger API Documentation Site