OpenAPI spec & Bruno collection

For machine-readable API access and quick local testing we provide:

• An OpenAPI 3.0 spec covering all public + Peppered endpoints.
• A Bruno collection you can import into the Bruno API client.

OpenAPI spec

Location in the repo: kb/api/_spec/openapi.yaml

Use it for:

• Generating API clients in any language (TypeScript, Python, Go, Java, …) via tools like OpenAPI Generator.
• Importing into Postman, Insomnia, or Bruno.
• Auto-generating documentation sites (Redoc, Stoplight).
• Writing validators / request builders.

The spec includes:

Section	What's in it
servers	Base URL with {client_name} as a server variable
components.securitySchemes.apiKey	API-key in Authorization header (raw value) for Peppered endpoints
components.schemas	Shared request/response schemas (Event, User, Cart, Order, Hall, …)
paths	All 31 endpoints, grouped by tag

Tags used:

• Public
• Peppered Customers
• Peppered Events
• Peppered Cart
• Peppered Orders
• Peppered Seating
• Peppered Payment
• Peppered Exports

Bruno collection

Location: bruno/VoordeMensen/ (in the repo root).

Getting started

1. Download and install Bruno: https://www.usebruno.com/downloads
2. Clone this docs repository.
3. In Bruno: Open Collection → pick the bruno/VoordeMensen/ folder.
4. Select the demo environment (top-right dropdown).
5. Adjust client_name and (for Peppered endpoints) api_key in the environment.

What's included

Public folder - 8 requests forming a complete ticketing flow:

1. List events
2. Get event (use upcoming to filter future events)
3. List ticket types
4. Create cart (stores cart_id automatically)
5. Add to cart
6. Get cart
7. Create order (stores order_key automatically)
8. Get order status

Each request chains via post-response scripts - run them in sequence to simulate a real checkout.

Peppered folder - 3 example requests requiring an API key:

1. Find customer by email
2. List events
3. Export orders

Importing the OpenAPI spec into Bruno

As an alternative to the hand-crafted collection, you can import the OpenAPI spec directly:

1. In Bruno: File → Import Collection → OpenAPI v3.
2. Select kb/api/_spec/openapi.yaml.
3. Bruno generates one request per endpoint.

This gives you all 31 endpoints at once (vs the 11 in the hand-crafted collection). Trade-off: less readable names and no automatic variable chaining.

Updates

The OpenAPI spec and Bruno collection are maintained alongside the narrative docs. When the API changes, both are updated in the same commit. See related_code in each endpoint doc for the controller source.

---

See also: Public endpoints · Peppered endpoints