Introduction

Blue's LTCR Workshop Booking API lets long-term-rental partner integrators — such as the team that operates bluecarrental.is — book workshop service appointments (tire change, oil and lube service, or other work) on behalf of the long-term-rental customers they serve, for the cars those customers are renting from Blue Car Rental.

Base URLs

API version

This document covers v1.5. All paths are prefixed with /api/v1/workshop. All timestamps are RFC 3339 in UTC. Requests and responses are JSON.

Getting started

Five steps to your first booking:

1. Request an API key from Blue Car Rental (see Authentication).
2. Call GET /api/v1/workshop/locations to list active workshop locations.
3. Call GET /api/v1/workshop/service-types to discover the bookable services and their duration, lead-time, and lookahead policy. Cache for up to 5 minutes.
4. Call GET /api/v1/workshop/availability with the location, the chosen service_type slug, and a date range. The returned slot grid already reflects that service type's duration.
5. Call POST /api/v1/workshop/bookings with the chosen slot, the same service_type, and the customer's contact details. The response includes a tokenised cancel URL Blue Car Rental will email the customer.

End-to-end example

# 1. List locations
curl -s https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/locations \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

# 2. Discover service types
curl -s https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/service-types \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

# 3. Check availability for "Dekk og smur" (60-min combined service) in Keflavík next week
curl -s "https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/availability?location=keflavik&service_type=dekk_smur&from=2026-05-19&to=2026-05-23" \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

# 4. Book the 09:00 slot on 2026-05-19
curl -s -X POST https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/bookings \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1c-7e2f-2026-05-19-keflavik-AB123" \
  -d '{
    "location": "keflavik",
    "slot_start_at": "2026-05-19T09:00:00Z",
    "service_type": "dekk_smur",
    "customer": {"name": "Kalli Bimbo", "email": "kalli@example.is", "phone": "+3546901588"},
    "license_plate": "AB123"
  }'

Authentication

Every request must include an API key in the X-API-Key header. Keys are issued by Blue Car Rental — there is no self-service signup.

Header

X-API-Key: bws_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Key format

An API key is three underscore-separated parts: a fixed scheme tag, a public prefix, and a secret.

Onboarding

Email Blue Car Rental to request a key. You will receive one production key and one staging key. Keys are not recoverable: if you lose a key, Blue Car Rental rotates it and issues a new one.

Rotation and deactivation

Blue Car Rental can deactivate any key at any time. To rotate, Blue Car Rental issues a new key and deactivates the old one — there is no in-place rotation. Your integration should handle:

• 401 unauthorized — the key is missing, malformed, deactivated, or no longer recognised. Stop sending requests with that key and contact Blue Car Rental.

Concepts

Locations

A location is a physical workshop site. The v1 launch ships with one location: keflavik (Keflavík). The schema is multi-location-ready; new locations are added over time by Blue Car Rental.

Slots and availability

Slots are not stored — they are derived per request from operating-hour rules, blackouts, and existing bookings. Always call /availability immediately before showing a calendar to the customer. Do not cache slots client-side. The server caches the response for 30 seconds.

Service types

A service type is a bookable service offered at a workshop — for example a tire change or a combined tires + oil-and-lube visit. Service types are a dynamic, policy-driven catalogue: Blue Car Rental can add new services, change durations, or adjust lead-time and lookahead policy at any time without an API version bump. Do not hard-code the catalogue in your integration.

Each active service type carries:

Discovery flow. Call GET /service-types on partner-backend startup (and at most every 5 minutes thereafter — the response is cacheable for max-age=300). Render the returned list to the customer. Pass the chosen slug to GET /availability as service_type, then to POST /bookings. A slug that is unknown or no longer active is rejected — see Errors.

The v1 slugs dekkjaskipti and smurthjonusta were renamed to dekk and smur. annad ("other") was retired from the partner-facing catalogue. Existing v1 bookings remain valid.

Idempotency

Required for safe integration. If your backend ever retries a POST /bookings call under any failure condition (timeout, 429, 5xx), an Idempotency-Key is the only way to prevent a duplicate booking. The POST /bookings endpoint accepts an Idempotency-Key header (≤255 characters). Replaying the same key with the same payload returns the original booking instead of creating a duplicate. Replaying the same key with a different payload returns 409 idempotency_conflict. Keys are honoured for 24 hours; after that they are pruned and a replay creates a new booking.

Replay returns a partial body. The replay response is the original 201 Created but with cancel_url omitted — the API stores only a hash of the cancel token, so the plaintext token cannot be re-derived after the first response. Your integration must persist cancel_url (or the token query-string value) from the first successful response and re-use that copy across retries. The customer's confirmation email contains the original tokenised link in either case.

Cancellation flow

When a booking is created, Blue Car Rental emails the customer a confirmation with a tokenised cancel link. The link target is a partner-operated page at the partner's customer-facing host — for example https://www.bluecarrental.is/langtimaleiga/afboka/{booking_id}?token={token}. The customer clicks the link and sees the partner's confirmation UI, and the partner page server-side calls GET /api/v1/workshop/bookings/{id}/cancel?token=... with the same token to actually perform the cancellation. On successful cancellation, Blue Car Rental sends the customer a second email confirming it. Both emails are queued and delivered asynchronously — the booking and cancellation API responses do not wait for SMTP.

Partner responsibility. Each partner must serve a page at the path embedded in the cancel URL (/langtimaleiga/afboka/{booking_id}?token={token}) on their customer-facing host and call the cancel API server-side from that page. The partner page is the place to add any customer-facing confirmation step, fraud checks, or downstream notifications the partner needs.

Rate limits

Exceeded → 429 rate_limited with a Retry-After header. Back off and retry.

Time zones

All slot_start_at values are UTC. The workshop in Keflavík operates in Atlantic/Reykjavik. Render times in the customer's local timezone in your UI, but always send and store UTC.

List locations

curl -s https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/locations \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "locations": [
    {"slug": "keflavik", "name": "Keflavík", "timezone": "Atlantic/Reykjavik"}
  ]
}

List service types

curl -s https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/service-types \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "service_types": [
    {
      "slug": "dekk",
      "display_name_is": "Dekkjaskipti",
      "display_name_en": "Tire change",
      "duration_minutes": 30,
      "min_lead_calendar_days": 1,
      "max_lookahead_days": 60,
      "sort_order": 10
    },
    {
      "slug": "smur",
      "display_name_is": "Smurþjónusta",
      "display_name_en": "Oil & lube service",
      "duration_minutes": 30,
      "min_lead_calendar_days": 1,
      "max_lookahead_days": 60,
      "sort_order": 20
    },
    {
      "slug": "dekk_smur",
      "display_name_is": "Dekk og smur",
      "display_name_en": "Tires + oil & lube",
      "duration_minutes": 60,
      "min_lead_calendar_days": 1,
      "max_lookahead_days": 60,
      "sort_order": 30
    }
  ]
}

Read schedule

curl -s "https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/schedule?location=keflavik" \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "location": "keflavik",
  "schedule": [
    {
      "day_of_week": 1,
      "open_time": "09:00",
      "close_time": "15:00",
      "slot_length_minutes": 30,
      "capacity": 1,
      "effective_from": "2026-05-20",
      "effective_until": null
    },
    {
      "day_of_week": 2,
      "open_time": "09:00",
      "close_time": "15:00",
      "slot_length_minutes": 30,
      "capacity": 1,
      "effective_from": "2026-05-20",
      "effective_until": null
    }
  ]
}

List holidays

curl -s "https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/holidays?location=keflavik&from=2026-06-01&to=2026-12-31" \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "location": "keflavik",
  "holidays": [
    {"date": "2026-06-17", "reason": "Þjóðhátíðardagur", "reason_en": "Icelandic National Day"},
    {"date": "2026-12-24", "reason": "Aðfangadagur", "reason_en": "Christmas Eve"},
    {"date": "2026-12-25", "reason": "Jóladagur", "reason_en": "Christmas Day"}
  ]
}

Check availability

curl -s "https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/availability?location=keflavik&service_type=dekk_smur&from=2026-05-19&to=2026-05-23" \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "buffer_hours": 24,
  "earliest_bookable_at": "2026-05-19T08:00:00Z",
  "location": "keflavik",
  "service_type": "dekk_smur",
  "slots": [
    {"start_at": "2026-05-19T09:00:00Z", "end_at": "2026-05-19T10:00:00Z"},
    {"start_at": "2026-05-19T10:00:00Z", "end_at": "2026-05-19T11:00:00Z"}
  ]
}

Create a booking

curl -s -X POST https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/bookings \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1c-7e2f-2026-05-19-keflavik-AB123" \
  -d '{
    "location": "keflavik",
    "slot_start_at": "2026-05-19T09:00:00Z",
    "service_type": "dekk_smur",
    "customer": {"name": "Kalli Bimbo", "email": "kalli@example.is", "phone": "+3546901588"},
    "license_plate": "AB123",
    "mileage": 12345,
    "message": "Vil skipta yfir í sumardekk og taka smurningu.",
    "locale": "en"
  }'

{
  "booking_id": "5f8e3b1c-4e2a-4a91-9b8f-2c7d6e5a4b3c",
  "status": "active",
  "location": "keflavik",
  "slot_start_at": "2026-05-19T09:00:00Z",
  "slot_end_at": "2026-05-19T10:00:00Z",
  "service_type": "dekk_smur",
  "locale": "en",
  "cancel_url": "https://www.bluecarrental.is/langtimaleiga/afboka/5f8e3b1c-4e2a-4a91-9b8f-2c7d6e5a4b3c?token=..."
}

Read a booking

curl -s https://ltcr-workshop-booking-api.bluecarrental.is/api/v1/workshop/bookings/5f8e3b1c-4e2a-4a91-9b8f-2c7d6e5a4b3c \
  -H "X-API-Key: bws_a1b2c3d4_<your-secret>"

{
  "booking_id": "5f8e3b1c-4e2a-4a91-9b8f-2c7d6e5a4b3c",
  "status": "active",
  "location": "keflavik",
  "slot_start_at": "2026-05-19T09:00:00Z",
  "slot_end_at": "2026-05-19T10:00:00Z",
  "service_type": "dekk_smur",
  "customer": {"name": "Kalli Bimbo", "email": "kalli@example.is", "phone": "+3546901588"},
  "license_plate": "AB123",
  "mileage": 12345,
  "message": "Vil skipta yfir í sumardekk og taka smurningu.",
  "locale": "en",
  "cancelled_at": null
}

Cancel a booking

{
  "booking_id": "5f8e3b1c-4e2a-4a91-9b8f-2c7d6e5a4b3c",
  "status": "cancelled",
  "cancelled_at": "2026-05-17T14:23:08Z"
}

Errors

Errors return a uniform JSON envelope:

{
  "error": "slot_taken",
  "message": "That slot was just booked. Please choose another time.",
  "details": {
    "slot_start_at": "2026-05-19T09:00:00Z"
  }
}

HTTP status codes

Retry guidance

• Retry 429 and 5xx with exponential backoff (e.g. 1s, 2s, 4s, 8s, cap at 60s).
• Always include the original Idempotency-Key when retrying POST /bookings — without it, retries may create duplicate bookings.
• Never retry any other 4xx.