---
title: "Public API for AI-assisted bookings"
description: "Via the public customer API you can search playrooms and create bookings up to a hosted
payment session, including directly through AI assistants. All paths live under /v1/
and are lowercase."
canonical_url: "https://www.my-playrooms.de/en/content/api"
---

# Public API for AI-assisted bookings

Via the public customer API you can search playrooms and create bookings up to a hosted
payment session, including directly through AI assistants. All paths live under `/v1/`
and are lowercase.

## Public endpoints

No API key is needed for searching and reading:

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/playrooms
      </code>
    </td>
    
    <td>
      Browse the playroom catalog (20 items per page)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/playrooms/{urlPath}
      </code>
    </td>
    
    <td>
      Details for a playroom
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/playrooms/{urlPath}/booking-options
      </code>
    </td>
    
    <td>
      Available check-in/check-out times and prices
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/openapi.json
      </code>
    </td>
    
    <td>
      OpenAPI description of the whole API
    </td>
  </tr>
</tbody>
</table>

## Booking with an API key

Creating and paying a booking requires an API key, sent in the `X-API-Key` header:

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /v1/orders
      </code>
    </td>
    
    <td>
      Create a booking (requires <code>
        Idempotency-Key
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/orders/{orderId}
      </code>
    </td>
    
    <td>
      Status and details of a booking
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /v1/orders/{orderId}/payment
      </code>
    </td>
    
    <td>
      Create the payment link for a booking
    </td>
  </tr>
</tbody>
</table>

## Creating an API key

Create and manage your API keys yourself in your account under <user-api-keys-link>

API keys

</user-api-keys-link>

. The key is shown only **once** — store it securely. Bookings created with one of your keys are assigned to your account.

## OpenAPI specification

The complete machine-readable description of all endpoints, schemas and error cases lives at <api-link path="/v1/openapi.json">

/v1/openapi.json

</api-link>

.

## MCP server

AI assistants can use the same capabilities through the MCP server: <api-link path="/mcp">

/mcp

</api-link>

. It exposes the tools `search_playrooms`, `get_playroom`, `get_booking_options`, `create_booking`, `get_booking` and `create_payment_session`.

## Rules and versioning

- **Versioning** happens via the URL path (`/v1/`, later `/v2/`); all paths are lowercase.
- **Idempotency:** `POST /v1/orders` requires an `Idempotency-Key` header so repeated calls never create a duplicate booking.
- **Errors:** Application errors normally use `ProblemDetails` with `title`, `status`, and `detail`; do not rely on a stable `code` field.
- **Rate limiting:** The public API allows 200 requests per 60 seconds, partitioned by API key or client IP. There is no documented daily limit.
- **Webhooks:** The public API has no outgoing booking webhooks yet. Poll the order endpoint for status.