# Introduction

With the Bookingmood API you can access and manage your data in a programmatic way, using HTTP requests. The structure of the Bookingmood API is based on [PostgREST v14](https://docs.postgrest.org/en/v14/index.html).

## Base URL

All endpoints are relative to `https://api.bookingmood.com/v1`. Every request must be [authenticated](https://www.bookingmood.com/de-DE/api-reference/authentication) with an API key, which scopes all data to its organization.

## OpenAPI spec

The whole API, including the booking flow, is described in an [OpenAPI 3.0 spec](https://api.bookingmood.com/v1/openapi.json) with request and response schemas. Import it into tools like Postman or Insomnia, or use it to generate a typed client.

## Requests

Each [core resource](https://www.bookingmood.com/de-DE/api-reference/products) supports some or all of the following methods:

- `GET /{resource}` lists records. Use [selecting](https://www.bookingmood.com/de-DE/api-reference/selecting), [filtering](https://www.bookingmood.com/de-DE/api-reference/filtering) and [sorting & pagination](https://www.bookingmood.com/de-DE/api-reference/sorting-pagination) to shape the result.
- `POST /{resource}` creates one record, or several when the body is an array.
- `PATCH /{resource}` updates all records matching the filters.
- `DELETE /{resource}` deletes all records matching the filters.

Request bodies are JSON, sent with the `Content-Type: application/json` header. Updates and deletes without filters apply to every record you have access to, so always filter, for example on `id=eq.{id}`.

## Responses

Responses are JSON. By default the API sends `Prefer: count=exact, return=representation` to PostgREST, so:

- Creates, updates and deletes return the affected records.
- List responses include a `Content-Range` header with the returned range and the total number of matching records, for example `0-9/42`.

To change this, send your own `Prefer` header. For example, `Prefer: return=minimal` returns `204 No Content` for updates and deletes.

## Errors

The API uses conventional HTTP status codes:

- `400` The request is malformed, for example an unknown column, an invalid filter, or a body that doesn't match the endpoint's schema.
- `401` The API key is missing or invalid.
- `403` The API key has no permission for this record.
- `405` The resource does not exist, or the method is not available for it.
- `409` The request conflicts with existing data, for example a duplicate key.
- `5xx` Something went wrong on our side.

Errors have a JSON body following [the PostgREST error format](https://docs.postgrest.org/en/v14/references/errors.html), with a `code`, `message`, `details` and `hint`. When a request doesn't match an endpoint's schema, for example on the booking flow endpoints, the code is `BM400` and `details` lists each invalid field. Every request, including failed ones, is logged and can be inspected through the [API requests](https://www.bookingmood.com/de-DE/api-reference/api_requests) resource.

## Rate limits

The API currently has no rate limits. Please keep your usage reasonable: paginate large lists instead of fetching everything at once, and avoid polling more often than you need. Rate limits may be introduced in the future, in which case requests over the limit will receive a `429 Too Many Requests` response.

Example response headers

HTTP

```
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Range: 0-9/42
```

Example error

JSON

```
{
  "code": "PGRST204",
  "details": null,
  "hint": null,
  "message": "Could not find the 'nme' column of 'products' in the schema cache"
}
```