REST API

JSON over HTTPS. Bearer authentication. Eight endpoints cover discovery, decision, validation, and booking handoff.

Base URL

https://api.b2a.bluepillow.com/v1

Authentication

Every request carries an Authorization: Bearer pk_… header. See API keys.

Idempotency

All POST endpoints require an Idempotency-Key header (UUID v4 recommended). Retrying with the same key returns the cached response.

Endpoints

• POST /decide — stateless top-1 recommendation for a travel intent.
• POST /validate — re-price a previously-seen offer (±2% tolerance).
• POST /search/stays — ranked discovery search.
• GET /properties/{id} — canonical property record.
• POST /destinations/resolve + /discover-near — place lookup.
• POST /recommendations/by-hotel — best OTA for a chosen property.
• POST /bookings/initiate — tracked booking deep link.

Errors

Uniform error envelope. code is machine-stable; message is human-readable.

{
  "error": {
    "code": "invalid_request",
    "message": "field 'dates.check_in' is required",
    "field": "dates.check_in",
    "request_id": "req_01HXYZ...",
    "docs_url": "https://human.b2a.bluepillow.com/docs/api"
  }
}

Codes: invalid_request, authentication_failed, forbidden, not_found, conflict, rate_limited, upstream_unavailable, decision_expired, no_offers_found, internal_error.

Versioning

Optional B2A-Version: YYYY-MM-DD header pins behavior to a dated revision. Current: 2026-05-08.