# Holdspace.guru — Full API Documentation for AI Agents

> Dé marktplaats voor spirituele en bewuste ruimtes in heel Europa

## Over Holdspace

Holdspace.guru verbindt bezoekers met eigenaren van inspirerende ruimtes voor yoga, meditatie, workshops, retreats, trainingen en healing sessies. Het platform biedt een publieke REST API en een MCP server waarmee AI agents ruimtes kunnen zoeken en boekingen kunnen aanmaken.

## API Base URL

```
https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1
```

## Authenticatie

Geen authenticatie vereist. Alle endpoints zijn publiek toegankelijk.

---

## Endpoint 1: Discover Spaces

**GET** `/api-discover`

Zoek en ontdek beschikbare ruimtes met optionele filters.

### Parameters

| Parameter   | Type    | Verplicht | Beschrijving                                              |
|-------------|---------|-----------|----------------------------------------------------------|
| city        | string  | Nee       | Filter op stad (case-insensitive, substring match)        |
| activity    | string  | Nee       | Filter op activiteit (case-insensitive: "yoga" = "Yoga")  |
| capacity    | integer | Nee       | Minimale capaciteit (aantal personen)                     |
| overnight   | string  | Nee       | "true" om alleen locaties met overnachting te tonen       |
| location_id | uuid    | Nee       | Filter op locatie-ID (alle ruimtes binnen één locatie)    |
| lang        | string  | Nee       | Taal: nl (default), en, de, fr, es                       |
| limit       | integer | Nee       | Max resultaten 1-50 (default: 20)                        |
| offset      | integer | Nee       | Paginatie offset (default: 0)                            |

### Veelgebruikte activiteiten

Yoga, Pilates, Meditatie, Breathwork, Sound Healing, Workshops, Coaching, Retreats, Dans, Muziek, Training, Healing

### Voorbeeld request

```
GET https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-discover?city=Amsterdam&activity=Yoga&capacity=10&lang=en
```

### Voorbeeld cURL

```bash
curl -X GET "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-discover?city=Amsterdam&activity=Yoga&capacity=10&lang=en"
```

### Voorbeeld Python

```python
import requests

response = requests.get(
    "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-discover",
    params={
        "city": "Amsterdam",
        "activity": "Yoga",
        "capacity": 10,
        "lang": "en"
    }
)
spaces = response.json()
```

### Voorbeeld response

```json
{
  "meta": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "lang": "en",
    "api_version": "1.0.0"
  },
  "spaces": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Zen Yoga Loft",
      "description": "A spacious and light-filled yoga studio in the heart of Amsterdam with bamboo floors and floor-to-ceiling windows.",
      "city": "Amsterdam",
      "region": "Noord-Holland",
      "country": "NL",
      "capacity": 25,
      "square_meters": 80,
      "activities": ["Yoga", "Meditatie", "Breathwork"],
      "atmosphere": "Rustig en licht",
      "has_privacy_options": true,
      "is_featured": true,
      "photos": [
        "https://holdspace.guru/storage/spaces/zen-yoga-loft-1.jpg",
        "https://holdspace.guru/storage/spaces/zen-yoga-loft-2.jpg"
      ],
      "location": {
        "name": "Yoga House Amsterdam",
        "address": "Herengracht 100, 1015 BS Amsterdam",
        "city": "Amsterdam",
        "overnight_possible": false,
        "lunch_available": true,
        "coordinates": {
          "lat": 52.3676,
          "lng": 4.9041
        }
      },
      "links": {
        "detail": "https://holdspace.guru/space/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "book": "https://holdspace.guru/book/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ]
}
```

---

## Endpoint 2: Discover Locations

**GET** `/api-discover-locations`

Zoek en ontdek beschikbare locaties met optionele filters. Locaties zijn de fysieke plekken waar meerdere ruimtes zich kunnen bevinden.

### Parameters

| Parameter  | Type    | Verplicht | Beschrijving                                              |
|------------|---------|-----------|----------------------------------------------------------|
| city       | string  | Nee       | Filter op stad (case-insensitive, substring match)        |
| region     | string  | Nee       | Filter op regio/provincie (bijv. Noord-Holland)           |
| country    | string  | Nee       | Filter op land (bijv. NL, BE)                            |
| overnight  | string  | Nee       | "true" om alleen locaties met overnachting te tonen       |
| lang       | string  | Nee       | Taal: nl (default), en, de, fr, es                       |
| limit      | integer | Nee       | Max resultaten 1-50 (default: 20)                        |
| offset     | integer | Nee       | Paginatie offset (default: 0)                            |

### Voorbeeld request

```
GET https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-discover-locations?city=Amsterdam&overnight=true&lang=en
```

### Voorbeeld response

```json
{
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0,
    "lang": "en",
    "api_version": "1.0"
  },
  "locations": [
    {
      "id": "loc-uuid-123",
      "name": "Yoga House Amsterdam",
      "description": "A beautiful wellness center in the heart of Amsterdam with multiple yoga studios and retreat facilities.",
      "city": "Amsterdam",
      "region": "Noord-Holland",
      "country": "NL",
      "address": "Herengracht 100, 1015 BS Amsterdam",
      "coordinates": {
        "lat": 52.3676,
        "lng": 4.9041
      },
      "overnight": {
        "possible": true,
        "description": "5 private rooms available for overnight stays"
      },
      "dining": {
        "lunch_available": true,
        "self_catering": false
      },
      "accessibility": {
        "car": "Paid parking nearby",
        "public_transport": "5 min walk from tram stop",
        "train": "10 min walk from Amsterdam Central"
      },
      "photos": [
        "https://holdspace.guru/storage/locations/yoga-house-1.jpg"
      ],
      "links": {
        "detail": "https://holdspace.guru/locations/loc-uuid-123",
        "spaces": "https://holdspace.guru/spaces?location=loc-uuid-123",
        "api_spaces": "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-discover?location_id=loc-uuid-123"
      }
    }
  ]
}
```

---

## Endpoint 3: Natural Language Search

**POST** `/natural-language-search`

Zoek ruimtes met natuurlijke taal queries. De AI begrijpt verzoeken zoals "rustige yoga ruimte in Utrecht voor 20 personen" of "meditatie ruimte met overnachting".

### Request body (JSON)

| Veld  | Type   | Verplicht | Beschrijving                                    |
|-------|--------|-----------|------------------------------------------------|
| query | string | Ja        | Natuurlijke taal zoekopdracht in Nederlands of Engels |

### Voorbeeld request

```bash
curl -X POST "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/natural-language-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rustige yoga ruimte in Utrecht voor 20 personen met overnachting"
  }'
```

### Voorbeeld response

```json
{
  "filters": {
    "activities": ["yoga"],
    "city": "Utrecht",
    "minCapacity": 20,
    "overnightPossible": true,
    "atmosphere": "rustig"
  },
  "interpretation": "Je zoekt naar een rustige yoga ruimte in Utrecht voor minimaal 20 personen met overnachting"
}
```

De `filters` kunnen direct gebruikt worden met de `/api-discover` endpoint om relevante ruimtes te vinden.

---

## Endpoint 4: Check Availability

**POST** `/check-availability`

Controleer of een specifieke ruimte beschikbaar is voor een bepaalde datum en tijd voordat je een boeking maakt.

### Request body (JSON)

| Veld           | Type    | Verplicht | Beschrijving                                    |
|----------------|---------|-----------|------------------------------------------------|
| space_id       | uuid    | Ja        | ID van de ruimte (uit discover endpoint)         |
| start_datetime | string  | Ja        | Start in ISO 8601 (bijv. 2025-06-15T09:00:00+02:00) |
| end_datetime   | string  | Ja        | Einde in ISO 8601                               |
| room_index     | integer | Nee       | Ruimte-index bij multi-room locaties (default: 0)|

### Voorbeeld request

```bash
curl -X POST "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/check-availability" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "start_datetime": "2025-06-15T09:00:00+02:00",
    "end_datetime": "2025-06-15T17:00:00+02:00",
    "room_index": 0
  }'
```

### Voorbeeld response (beschikbaar)

```json
{
  "available": true,
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start_datetime": "2025-06-15T09:00:00+02:00",
  "end_datetime": "2025-06-15T17:00:00+02:00"
}
```

### Voorbeeld response (niet beschikbaar)

```json
{
  "available": false,
  "reason": "Dit tijdslot is al geboekt",
  "conflicts": [
    {
      "type": "booking",
      "start": "2025-06-15T09:00:00+02:00",
      "end": "2025-06-15T18:00:00+02:00",
      "reason": "Bestaande boeking"
    }
  ]
}
```

---

## Endpoint 5: Create Booking

**POST** `/api-book`

Maak een boekingsaanvraag aan voor een specifieke ruimte en tijdslot.

### Request body (JSON)

| Veld              | Type    | Verplicht | Beschrijving                                    |
|-------------------|---------|-----------|------------------------------------------------|
| space_id          | uuid    | Ja        | ID van de ruimte (uit discover endpoint)         |
| start_datetime    | string  | Ja        | Start in ISO 8601 (bijv. 2025-06-15T09:00:00+02:00) |
| end_datetime      | string  | Ja        | Einde in ISO 8601                               |
| customer_name     | string  | Ja        | Volledige naam van de boeker                     |
| customer_email    | email   | Ja        | E-mailadres voor bevestiging                     |
| customer_phone    | string  | Nee       | Telefoonnummer                                  |
| notes             | string  | Nee       | Opmerkingen of wensen                           |
| participant_count | integer | Nee       | Verwacht aantal deelnemers                       |
| room_index        | integer | Nee       | Ruimte-index bij multi-room locaties (default: 0)|

### Voorbeeld request

```bash
curl -X POST "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-book" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "start_datetime": "2025-06-15T09:00:00+02:00",
    "end_datetime": "2025-06-15T17:00:00+02:00",
    "customer_name": "Jan de Vries",
    "customer_email": "jan@voorbeeld.nl",
    "participant_count": 15,
    "notes": "Yogaretreat voor gevorderden, graag extra yogamatten"
  }'
```

### Voorbeeld Python

```python
import requests

response = requests.post(
    "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/api-book",
    json={
        "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "start_datetime": "2025-06-15T09:00:00+02:00",
        "end_datetime": "2025-06-15T17:00:00+02:00",
        "customer_name": "Jan de Vries",
        "customer_email": "jan@voorbeeld.nl",
        "participant_count": 15,
        "notes": "Yogaretreat voor gevorderden"
    }
)
booking = response.json()
```

### Voorbeeld response (201 Created)

```json
{
  "success": true,
  "booking": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "pending",
    "space_name": "Zen Yoga Loft",
    "location_name": "Yoga House Amsterdam",
    "start_datetime": "2025-06-15T09:00:00+02:00",
    "end_datetime": "2025-06-15T17:00:00+02:00",
    "price": {
      "total_cents": 35000,
      "currency": "EUR",
      "formatted": "€350,00",
      "includes_vat": true
    }
  },
  "next_steps": {
    "message": "De boeking is aangemaakt met status 'pending'. De eigenaar zal deze beoordelen en je ontvangt een bevestiging per e-mail.",
    "detail_url": "https://holdspace.guru/pay/b2c3d4e5-f6a7-8901-bcde-f23456789012"
  }
}
```

### Foutresponses

**409 Conflict** — Tijdslot niet beschikbaar:
```json
{
  "success": false,
  "available": false,
  "reason": "Dit tijdslot is al geboekt",
  "suggestion": "Probeer een ander tijdslot of een andere datum"
}
```

**400 Bad Request** — Ongeldige parameters:
```json
{
  "error": "Verplichte velden ontbreken: space_id, start_datetime, end_datetime, customer_name, customer_email"
}
```

**404 Not Found** — Ruimte niet gevonden:
```json
{
  "error": "Space not found"
}
```

---

## MCP Server (Model Context Protocol)

AI agents die MCP ondersteunen (Claude, Cursor, Windsurf) kunnen direct verbinden met de MCP server.

### Configuratie

```json
{
  "mcpServers": {
    "holdspace": {
      "url": "https://qdvqoeeucscjgpwiguom.supabase.co/functions/v1/mcp-server",
      "transport": "streamable-http"
    }
  }
}
```

### Beschikbare tools

| Tool                    | Beschrijving                                                    |
|-------------------------|----------------------------------------------------------------|
| discover_spaces         | Zoek ruimtes met filters (stad, activiteit, capaciteit, overnachting) |
| discover_locations      | Zoek locaties met filters (stad, regio, land, overnachting)     |
| natural_language_search | Zoek met natuurlijke taal ("rustige yoga ruimte in Utrecht")    |
| check_availability      | Controleer beschikbaarheid voor een specifieke datum/tijd        |
| book_space              | Maak een boekingsaanvraag aan                                   |

---

## Typische AI Agent Workflow

### Optie 1: Directe zoekopdracht (als specifieke eisen bekend zijn)
1. **Zoek ruimtes**: `GET /api-discover?city=Utrecht&activity=Meditatie&capacity=8`
2. **Check beschikbaarheid**: `POST /check-availability` voor de gewenste datum/tijd
3. **Boek**: `POST /api-book` met space_id, datum/tijd en contactgegevens
4. **Informeer de gebruiker**: Deel de booking ID, prijs en detail URL

### Optie 2: Natuurlijke taal workflow (gebruiker spreekt vrije tekst)
1. **Parse query**: `POST /natural-language-search` met "rustige yoga ruimte in Utrecht voor 20 personen"
2. **Gebruik filters**: Gebruik de geretourneerde filters met `GET /api-discover`
3. **Check beschikbaarheid**: `POST /check-availability` voor de gewenste datum/tijd
4. **Boek**: `POST /api-book` met space_id, datum/tijd en contactgegevens

### Optie 3: Locatie-first workflow
1. **Zoek locaties**: `GET /api-discover-locations?city=Amsterdam&overnight=true`
2. **Zoek ruimtes in locatie**: `GET /api-discover?location_id=<id>`
3. **Check beschikbaarheid**: `POST /check-availability` voor de gewenste datum/tijd
4. **Boek**: `POST /api-book` met space_id, datum/tijd en contactgegevens

**Na boeking**: De eigenaar bevestigt de boeking en de klant betaalt via de betaalpagina.

## Rate Limits

- Discover endpoints: 30 requests per minuut per IP
- Check availability: 60 requests per minuut per IP
- Natural language search: 5 requests per minuut per IP (cached, herhaalde queries kosten geen credits)
- Booking endpoint: 10 requests per 5 minuten per IP

## Steden met beschikbare ruimtes

Amsterdam, Utrecht, Rotterdam, Den Haag, Haarlem, Leiden, Arnhem, Nijmegen, Groningen, Eindhoven, Maastricht, Breda, Den Bosch, Delft, Amersfoort, Antwerpen, Gent, Brugge, Brussel, Leuven

## Contact

- Website: https://holdspace.guru
- E-mail: hello@holdspace.guru
- OpenAPI spec: https://holdspace.guru/openapi.json
- AI Plugin manifest: https://holdspace.guru/.well-known/ai-plugin.json