What agents can do

Amsterdam Experiences offers private guided tours in Amsterdam and across the Netherlands and Belgium. Through the public REST API, an agent can:

Retrieve the full catalogue of available tours, with filtering by duration, keyword or category
Fetch detailed information about any individual tour
Submit a booking enquiry on behalf of a guest

No API key or authentication is required. All endpoints are publicly accessible.

Base URL

https://amsterdamexperiences.nl/wp-json/aex/v1/

The full OpenAPI 3.1 specification is at https://amsterdamexperiences.nl/wp-json/aex/v1/openapi.

Endpoints

GET /tours

Returns all available tours as a JSON array.

Query parameters:

search — Keyword search. Every word must match in the tour name, slug, description or categories.
category — Additional keyword filter applied to tour categories.
group — Duration filter: a for half-day tours (up to approximately four hours), b for full-day tours.
page — Page number for pagination, starting at 1.
per_page — Number of results per page. Default is 20.

Response: array of tour objects, each with:

id — Integer. Internal identifier.
slug — String. URL-safe identifier. Use this in single-tour requests and enquiries.
name — String. Tour name.
group — String. a (half-day) or b (full day).
description — String. Short tour description.
tour_type — String. private (exclusive to your group) or small_group (shared).
max_guests — Integer. Maximum group size.
group_size_note — String or null. Human-readable note on group size.
price_from — Number. Starting price in EUR for the whole group. Omitted when pricing_on_request is true.
currency — String. Always EUR.
booking_url — String. URL to the full tour page on this website.
pricing_on_request — Boolean. When true, price is confirmed on enquiry rather than published.

GET /tours/{slug}

Returns a single tour by its slug. Same fields as above, with fuller detail where available. Returns HTTP 404 with an error object if no tour matches the slug.

POST /inquiry

Submits a booking enquiry. The team reviews every enquiry and replies within 24 hours. No date is held and nothing is booked automatically.

Request body (JSON):

{
  "tour_slug": "amsterdam-highlights",
  "date": "2026-05-15",
  "guests": 4,
  "name": "Jane Smith",
  "email": "moc.elpmaxe@enaj",
  "message": "We would like a private tour starting at 10am."
}

Fields:

tour_slug — Required. Slug from GET /tours.
date — Required. Preferred date in YYYY-MM-DD format.
guests — Required. Number of guests (integer).
name — Required. Guest name.
email — Required. Guest email address.
message — Optional. Additional requirements: pick-up location, language preference, accessibility needs.

Success response (HTTP 201):

{
  "status": "received",
  "message": "Thank you, we will reply within 24 hours."
}

Validation errors return HTTP 422. The rate limit is 10 enquiries per hour per IP address.

Error format

All error responses use this structure:

{
  "error": {
    "code": "not_found",
    "message": "No tour found with that slug.",
    "type": "client_error"
  }
}

code — Machine-readable string. Common values: not_found, validation_error, rate_limit_exceeded.
message — Human-readable explanation.
type — client_error for 4xx responses, server_error for 5xx responses.

On a server_error or HTTP 5xx response, wait at least two seconds and retry with the same Idempotency-Key. Do not retry on 4xx responses.

Rate limiting

Every response includes these headers:

RateLimit-Limit — Requests allowed in the current window.
RateLimit-Remaining — Requests remaining before the limit is reached.
RateLimit-Reset — Unix timestamp at which the window resets.

HTTP 429 is returned when the limit is reached. Read RateLimit-Reset to determine when to retry.

Idempotency

Include an Idempotency-Key header on every POST /inquiry request. Generate a UUID v4 for each unique submission attempt. If a request times out or returns a 5xx error, retrying with the same key prevents a duplicate enquiry from being created.

Pagination

Use the page and per_page parameters on GET /tours. The default page size is 20. When a response returns exactly per_page items, increment page and fetch again. Stop when a response returns fewer than per_page items.

Recommended booking flow

Call GET /tours to retrieve available tours. Use group=a for half-day tours or group=b for full-day tours, and search to match a keyword or destination.
Call GET /tours/{slug} for full details on a chosen tour, including the booking_url.
Call POST /inquiry with the guest’s preferred date, group size, name and email. Include an Idempotency-Key header. Add any special requirements in the message field.
The team will reply by email within 24 hours to confirm availability and finalise the booking.

Enquiries do not hold dates or guarantee availability. Mention pick-up location, language preferences or accessibility needs in the message field.

Machine-readable resources

OpenAPI 3.1 specification
llms.txt — Full AI guide in plain text
agents.md — Agent entry point document
Agent card — A2A protocol
AI plugin manifest

About Amsterdam Experiences

Bespoke Amsterdam Experiences is a private guided tour operator based in Amsterdam, the Netherlands. We specialise in private and small-group tours in Amsterdam, day trips to the Dutch countryside, and multi-day tours through the Netherlands and Belgium.

For questions: ln.secneirepxemadretsma@ofni.

For Agents