{"openapi":"3.1.0","info":{"title":"Bagdock API","version":"1.0.0","description":"Unified API for self-storage marketplace, loyalty, IoT, and operator management.","contact":{"name":"Bagdock Engineering","url":"https://docs.bagdock.com"}},"servers":[{"url":"https://api.bagdock.com","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"paths":{"/api/v1/locations":{"get":{"tags":["Marketplace — Locations"],"summary":"Search locations","operationId":"searchLocations","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"postcode","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for forward pagination (last item id)."},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor for backward pagination (first item id)."}],"responses":{"200":{"description":"Paginated list of locations"}}}},"/api/v1/locations/{id}":{"get":{"tags":["Marketplace — Locations"],"summary":"Get location details","operationId":"getLocation","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Location details"}}}},"/api/v1/locations/{id}/units":{"get":{"tags":["Marketplace — Locations"],"summary":"List units at a location","operationId":"listUnits","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"string","enum":["small","medium","large","extra_large"]}},{"name":"available_only","in":"query","schema":{"type":"boolean","default":true}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for forward pagination (last item id)."},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor for backward pagination (first item id)."}],"responses":{"200":{"description":"Paginated list of units"}}}},"/api/v1/search":{"get":{"tags":["Marketplace — Search"],"summary":"Search across listings, facilities, and units","operationId":"searchAll","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"size","in":"query","schema":{"type":"string","enum":["small","medium","large","extra_large"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for forward pagination (last item id)."},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor for backward pagination (first item id)."}],"responses":{"200":{"description":"Search results"}}}},"/api/v1/rentals/create":{"post":{"tags":["Customer — Rentals"],"summary":"Create a new rental","operationId":"createRental","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["locationId","userId","date","startTime","duration","quantity","rentalType","totalPrice","customerEmail","customerName"],"properties":{"locationId":{"type":"string","format":"uuid"},"userId":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"startTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"duration":{"type":"integer","minimum":1,"maximum":30},"quantity":{"type":"integer","minimum":1,"maximum":10},"lockerSize":{"type":"string","enum":["small","standard","maxi"]},"rentalType":{"type":"string","enum":["locker","item"]},"totalPrice":{"type":"number"},"customerEmail":{"type":"string","format":"email"},"customerName":{"type":"string"}}}}}},"responses":{"201":{"description":"Rental created"}}}},"/api/v1/rentals/reference/{code}":{"get":{"tags":["Customer — Rentals"],"summary":"Get rental by reference code","operationId":"getRentalByReference","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rental details"}}}},"/api/v1/rentals/{id}/status":{"patch":{"tags":["Customer — Rentals"],"summary":"Update rental status","operationId":"updateRentalStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["confirmed","active","completed","cancelled"]},"accessCode":{"type":"string"}}}}}},"responses":{"200":{"description":"Status updated"}}}},"/api/v1/sessions":{"post":{"tags":["Checkout — Sessions"],"summary":"Create a checkout session","operationId":"createCheckoutSession","parameters":[{"$ref":"#/components/parameters/BagdockVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["facility_id","move_in_date"],"properties":{"facility_id":{"type":"string"},"unit_id":{"type":"string"},"unit_type_id":{"type":"string"},"move_in_date":{"type":"string","format":"date"},"move_out_date":{"type":"string","format":"date"},"duration_days":{"type":"integer","minimum":1},"billing_frequency":{"type":"string","enum":["weekly","every_four_weeks","monthly","every_three_months","every_six_months","yearly"]},"amount_subtotal_pence":{"type":"integer"},"amount_tax_pence":{"type":"integer"},"amount_total_pence":{"type":"integer"},"currency":{"type":"string","enum":["GBP","USD","EUR"]},"ttl_minutes":{"type":"integer","minimum":5,"maximum":1440},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"contact_id":{"type":"string"},"contact_email":{"type":"string","format":"email"},"contact_phone":{"type":"string"},"contact_name":{"type":"string"},"is_guest":{"type":"boolean"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Session created"}}},"get":{"tags":["Checkout — Sessions"],"summary":"List checkout sessions","operationId":"listCheckoutSessions","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"facility_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","complete","expired","cancelled"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of sessions"}}}},"/api/v1/sessions/{session_id}":{"get":{"tags":["Checkout — Sessions"],"summary":"Get checkout session","operationId":"getCheckoutSession","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session details"}}}},"/api/v1/availability/check":{"post":{"tags":["Marketplace — Availability"],"summary":"Check availability for locations","operationId":"checkAvailability","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["locationIds"],"properties":{"locationIds":{"type":"array","items":{"type":"string","format":"uuid"}},"dropOffDate":{"type":"string","format":"date-time"},"pickUpDate":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Availability results"}}}},"/api/loyalty/points/balance":{"get":{"tags":["Loyalty — Points"],"summary":"Get points balance","operationId":"getPointsBalance","parameters":[{"name":"user_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Points balance"}}}},"/api/loyalty/points/history":{"get":{"tags":["Loyalty — Points"],"summary":"Get points transaction history","operationId":"getPointsHistory","parameters":[{"name":"user_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Points history"}}}},"/api/loyalty/points/award":{"post":{"tags":["Loyalty — Points"],"summary":"Award points to a member","operationId":"awardPoints","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","points","reason"],"properties":{"user_id":{"type":"string"},"points":{"type":"integer"},"reason":{"type":"string","enum":["signup_bonus","rental_reward","referral_bonus","adjustment"]},"reference_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Points awarded"}}}},"/api/loyalty/points/redeem":{"post":{"tags":["Loyalty — Points"],"summary":"Redeem points for a reward","operationId":"redeemPoints","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["points","reward_id"],"properties":{"points":{"type":"integer"},"reward_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Points redeemed"}}}},"/api/loyalty/rewards":{"get":{"tags":["Loyalty — Rewards"],"summary":"List available rewards","operationId":"listRewards","responses":{"200":{"description":"List of rewards"}}}},"/api/loyalty/rewards/{id}":{"get":{"tags":["Loyalty — Rewards"],"summary":"Get reward details","operationId":"getReward","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reward details"}}}},"/api/loyalty/rewards/{id}/claim":{"post":{"tags":["Loyalty — Rewards"],"summary":"Claim a reward","operationId":"claimReward","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reward claimed"}}}},"/api/loyalty/referrals":{"get":{"tags":["Loyalty — Referrals"],"summary":"List referrals","operationId":"listReferrals","responses":{"200":{"description":"List of referrals"}}},"post":{"tags":["Loyalty — Referrals"],"summary":"Create a referral","operationId":"createReferral","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["referred_email"],"properties":{"referred_email":{"type":"string","format":"email"},"referred_first_name":{"type":"string"},"referred_last_name":{"type":"string"}}}}}},"responses":{"201":{"description":"Referral created"}}}},"/api/loyalty/referrals/{id}":{"get":{"tags":["Loyalty — Referrals"],"summary":"Get referral status","operationId":"getReferral","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Referral details"}}}},"/api/loyalty/partners":{"get":{"tags":["Loyalty — Partners"],"summary":"List partners","operationId":"listPartners","responses":{"200":{"description":"List of partners"}}},"post":{"tags":["Loyalty — Partners"],"summary":"Register partner","operationId":"registerPartner","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partner_type","business_name","contact_email"],"properties":{"partner_type":{"type":"string","enum":["brand","operator","affiliate","publisher","agency","individual"]},"business_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"enable_referral_rewards":{"type":"boolean","default":true},"referral_commission_percent":{"type":"number","default":5}}}}}},"responses":{"201":{"description":"Partner registered"}}}},"/api/loyalty/partners/{id}":{"get":{"tags":["Loyalty — Partners"],"summary":"Get partner details","operationId":"getPartner","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner details"}}},"patch":{"tags":["Loyalty — Partners"],"summary":"Update partner","operationId":"updatePartner","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner updated"}}}},"/api/loyalty/auth/authenticate":{"post":{"tags":["Loyalty — Auth"],"summary":"Authenticate member","operationId":"authenticateMember","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Authentication successful"}},"security":[]}},"/api/loyalty/auth/refresh":{"post":{"tags":["Loyalty — Auth"],"summary":"Refresh access token","operationId":"refreshToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Token refreshed"}},"security":[]}},"/api/loyalty/auth/revoke":{"post":{"tags":["Loyalty — Auth"],"summary":"Revoke refresh token","operationId":"revokeToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Token revoked"}},"security":[]}},"/api/v1/devices":{"get":{"tags":["IoT — Devices"],"summary":"List IoT devices","operationId":"listDevices","responses":{"200":{"description":"List of devices"}}}},"/api/v1/devices/{device_id}":{"get":{"tags":["IoT — Devices"],"summary":"Get device details","operationId":"getDevice","parameters":[{"name":"device_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Device details"}}}},"/api/v1/facilities":{"get":{"tags":["Operator — Facilities"],"summary":"List facilities","operationId":"listFacilities","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of facilities"}}},"post":{"tags":["Operator — Facilities"],"summary":"Create facility","operationId":"createFacility","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Facility created"}}}},"/api/v1/facilities/{id}":{"get":{"tags":["Operator — Facilities"],"summary":"Get facility","operationId":"getFacility","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Facility details"}}},"patch":{"tags":["Operator — Facilities"],"summary":"Update facility","operationId":"updateFacility","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Facility updated"}}}},"/api/v1/units":{"get":{"tags":["Operator — Units"],"summary":"List units","operationId":"listOperatorUnits","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"facility_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["available","occupied","reserved","maintenance"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of units"}}}},"/api/v1/units/{id}":{"get":{"tags":["Operator — Units"],"summary":"Get unit","operationId":"getOperatorUnit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unit details"}}},"patch":{"tags":["Operator — Units"],"summary":"Update unit","operationId":"updateOperatorUnit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Unit updated"}}}},"/api/v1/contacts":{"get":{"tags":["Operator — Contacts"],"summary":"List contacts","operationId":"listContacts","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of contacts"}}},"post":{"tags":["Operator — Contacts"],"summary":"Create contact","operationId":"createContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Contact created"}}}},"/api/v1/contacts/{id}":{"get":{"tags":["Operator — Contacts"],"summary":"Get contact","operationId":"getContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact details"}}},"patch":{"tags":["Operator — Contacts"],"summary":"Update contact","operationId":"updateContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Contact updated"}}}},"/api/v1/billing-accounts":{"get":{"tags":["Operator — Billing"],"summary":"List billing accounts","operationId":"listBillingAccounts","responses":{"200":{"description":"List of billing accounts"}}}},"/api/v1/invoices":{"get":{"tags":["Operator — Billing"],"summary":"List invoices","operationId":"listInvoices","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","open","paid","void","uncollectible"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of invoices"}}}},"/api/v1/operator-rules":{"get":{"tags":["Operator — Agent Rules"],"summary":"List agent rules","operationId":"listOperatorRules","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["pricing","negotiation","escalation","response","custom"]}}],"responses":{"200":{"description":"List of agent rules"}}},"post":{"tags":["Operator — Agent Rules"],"summary":"Create agent rule","operationId":"createOperatorRule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","category","rule_text"],"properties":{"name":{"type":"string"},"category":{"type":"string","enum":["pricing","negotiation","escalation","response","custom"]},"rule_text":{"type":"string"},"priority":{"type":"integer","default":0},"is_active":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Rule created"}}}},"/api/v1/operator-rules/{id}":{"get":{"tags":["Operator — Agent Rules"],"summary":"Get agent rule","operationId":"getOperatorRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rule details"}}},"patch":{"tags":["Operator — Agent Rules"],"summary":"Update agent rule","operationId":"updateOperatorRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Rule updated"}}},"delete":{"tags":["Operator — Agent Rules"],"summary":"Delete agent rule","operationId":"deleteOperatorRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rule deleted"}}}},"/api/v1/operator/valet/zones":{"get":{"tags":["Operator — Valet"],"summary":"List service zones","operationId":"listValetZones","responses":{"200":{"description":"List of zones"}}},"post":{"tags":["Operator — Valet"],"summary":"Create service zone","operationId":"createValetZone","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]}}}}}},"responses":{"201":{"description":"Zone created"}}}},"/api/v1/operator/valet/orders":{"get":{"tags":["Operator — Valet"],"summary":"List valet orders","operationId":"listValetOrders","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","confirmed","in_transit","completed","cancelled"]}}],"responses":{"200":{"description":"List of orders"}}},"post":{"tags":["Operator — Valet"],"summary":"Create valet order","operationId":"createValetOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["zone_id","contact_id","order_type","scheduled_date","address"]}}}},"responses":{"201":{"description":"Order created"}}}},"/api/v1/operator/valet/items":{"get":{"tags":["Operator — Valet"],"summary":"List stored items","operationId":"listValetItems","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["in_storage","in_transit","returned","disposed"]}}],"responses":{"200":{"description":"List of items"}}}},"/api/v1/vendors":{"get":{"tags":["Marketplace — Vendors"],"summary":"List marketplace vendors","operationId":"listVendors","parameters":[{"$ref":"#/components/parameters/BagdockVersion"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of vendors"}}}},"/api/v1/vendors/{id}":{"get":{"tags":["Marketplace — Vendors"],"summary":"Get vendor details","operationId":"getVendor","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vendor details"}}}},"/api/loyalty/members":{"get":{"tags":["Loyalty — Members"],"summary":"List members","operationId":"listMembers","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of members"}}},"post":{"tags":["Loyalty — Members"],"summary":"Create member","operationId":"createMember","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}},"responses":{"201":{"description":"Member created"}}}},"/api/loyalty/members/{id}":{"get":{"tags":["Loyalty — Members"],"summary":"Get member","operationId":"getMember","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Member details"}}},"patch":{"tags":["Loyalty — Members"],"summary":"Update member","operationId":"updateMember","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Member updated"}}}},"/api/loyalty/programs":{"get":{"tags":["Loyalty — Programs"],"summary":"List programs","operationId":"listPrograms","responses":{"200":{"description":"List of programs"}}},"post":{"tags":["Loyalty — Programs"],"summary":"Create program","operationId":"createProgram","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Program created"}}}},"/api/loyalty/programs/{id}":{"get":{"tags":["Loyalty — Programs"],"summary":"Get program","operationId":"getProgram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Program details"}}},"patch":{"tags":["Loyalty — Programs"],"summary":"Update program","operationId":"updateProgram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Program updated"}}}},"/api/v1/agent/sessions":{"get":{"tags":["Agent — Sessions"],"summary":"List agent sessions","operationId":"listAgentSessions","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","closed","handed_off"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of sessions"}}},"post":{"tags":["Agent — Sessions"],"summary":"Create agent session","operationId":"createAgentSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["web_widget","embed","api","whatsapp","sms"]}}}}}},"responses":{"201":{"description":"Session created"}}}},"/api/v1/agent/sessions/{sessionId}":{"get":{"tags":["Agent — Sessions"],"summary":"Get agent session","operationId":"getAgentSession","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session details"}}}},"/api/v1/agent/handoff":{"post":{"tags":["Agent — Handoffs"],"summary":"Create handoff","operationId":"createHandoff","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","reason"],"properties":{"session_id":{"type":"string"},"reason":{"type":"string","enum":["customer_request","complex_query","escalation","negotiation_limit","technical_issue"]},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal"}}}}}},"responses":{"201":{"description":"Handoff created"}}}},"/api/v1/agent/handoffs":{"get":{"tags":["Agent — Handoffs"],"summary":"List handoffs","operationId":"listHandoffs","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","accepted","resolved","expired"]}}],"responses":{"200":{"description":"List of handoffs"}}}},"/api/customer/health":{"get":{"tags":["Health"],"summary":"Customer API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/loyalty/health":{"get":{"tags":["Health"],"summary":"Loyalty API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/iot/health":{"get":{"tags":["Health"],"summary":"IoT API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/operator/health":{"get":{"tags":["Health"],"summary":"Operator API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/marketplace/health":{"get":{"tags":["Health"],"summary":"Marketplace API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/checkout/health":{"get":{"tags":["Health"],"summary":"Checkout API health","responses":{"200":{"description":"OK"}},"security":[]}},"/api/graphql/health":{"get":{"tags":["Health"],"summary":"GraphQL Gateway health","responses":{"200":{"description":"OK"}},"security":[]}},"/graphql":{"post":{"tags":["GraphQL"],"summary":"Unified GraphQL endpoint","operationId":"graphql","description":"Stitched schema spanning operator, marketplace, IoT, loyalty, customer, and checkout subgraphs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"variables":{"type":"object"}}}}}},"responses":{"200":{"description":"GraphQL response"}}}}},"components":{"parameters":{"BagdockVersion":{"name":"Bagdock-Version","in":"header","schema":{"type":"string","example":"2026-03-06"},"description":"API version (date-based). Defaults to latest if omitted."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use sk_live_* keys for production or sk_test_* keys for sandbox."},"oauth2":{"type":"oauth2","description":"OAuth 2.0. Supports the authorizationCode and clientCredentials flows below, plus the device authorization grant (RFC 8628, urn:ietf:params:oauth:grant-type:device_code via POST /oauth2/device/authorize then POST /oauth2/token) — not representable as an OpenAPI 3.1 flow object. Authorization code flow requires PKCE (S256).","flows":{"authorizationCode":{"authorizationUrl":"https://api.bagdock.com/oauth2/authorize","tokenUrl":"https://api.bagdock.com/oauth2/token","scopes":{"contacts:read":"Read access to Contacts","contacts:write":"Write access to Contacts","companies:read":"Read access to Companies","companies:write":"Write access to Companies","units:read":"Read access to Units","units:write":"Write access to Units","units:manage":"Manage access to Units","facilities:read":"Read access to Facilities","facilities:write":"Write access to Facilities","rentals:read":"Read access to Rentals","rentals:write":"Write access to Rentals","subscriptions:read":"Read access to Subscriptions","subscriptions:write":"Write access to Subscriptions","tenancies:read":"Read access to Tenancies","tenancies:write":"Write access to Tenancies","listings:read":"Read access to Listings","listings:write":"Write access to Listings","products:read":"Read access to Products","products:write":"Write access to Products","unit_types:read":"Read access to Unit types","unit_types:write":"Write access to Unit types","deals:read":"Read access to Deals","deals:write":"Write access to Deals","goals:read":"Read access to Goals","goals:write":"Write access to Goals","marketing_events:read":"Read access to Marketing events","marketing_events:write":"Write access to Marketing events","segments:read":"Read access to Segments","segments:write":"Write access to Segments","waitlist:read":"Read access to Waitlist","waitlist:write":"Write access to Waitlist","invoices:read":"Read access to Invoices","invoices:write":"Write access to Invoices","payments:read":"Read access to Payments","payments:write":"Write access to Payments","deposits:read":"Read access to Deposits","deposits:write":"Write access to Deposits","contracts:read":"Read access to Contracts","contracts:write":"Write access to Contracts","collections:read":"Read access to Collections","collections:write":"Write access to Collections","accounting:read":"Read access to Accounting","accounting:write":"Write access to Accounting","pricing_rules:read":"Read access to Pricing rules","pricing_rules:write":"Write access to Pricing rules","tax_rates:read":"Read access to Tax rates","tax_rates:write":"Write access to Tax rates","checkout:read":"Read access to Checkout","checkout:write":"Write access to Checkout","verification:read":"Read access to Identity verification","verification:write":"Write access to Identity verification","comms:read":"Read access to Callbacks & scheduling","comms:write":"Write access to Callbacks & scheduling","negotiations:read":"Read access to Negotiations","negotiations:write":"Write access to Negotiations","loyalty:read":"Read access to Loyalty","loyalty:write":"Write access to Loyalty","protection:read":"Read access to Protection policies","protection:write":"Write access to Protection policies","projects:read":"Read access to Projects","projects:write":"Write access to Projects","issues:read":"Read access to Issues","issues:write":"Write access to Issues","tasks:read":"Read access to Tasks","tasks:write":"Write access to Tasks","notes:read":"Read access to Notes","notes:write":"Write access to Notes","orders:read":"Read access to Orders","orders:write":"Write access to Orders","valet:read":"Read access to Valet","valet:write":"Write access to Valet","labels:read":"Read access to Labels","labels:write":"Write access to Labels","move_events:read":"Read access to Move events","move_events:write":"Write access to Move events","workflows:read":"Read access to Workflows","workflows:write":"Write access to Workflows","conversations:read":"Read access to Conversations","conversations:write":"Write access to Conversations","tickets:read":"Read access to Tickets","tickets:write":"Write access to Tickets","calls:read":"Read access to Calls","calls:write":"Write access to Calls","access:read":"Read access to Access","access:write":"Write access to Access","access_codes:read":"Read access to Access codes","access_codes:write":"Write access to Access codes","access_systems:read":"Read access to Access systems","access_systems:write":"Write access to Access systems","analytics:read":"Read access to Analytics","reports:read":"Read access to Reports","iot:read":"Read access to IoT devices","iot:write":"Write access to IoT devices","webhooks:read":"Read access to Webhooks","webhooks:write":"Write access to Webhooks","hive:read":"Read access to Hive (embed & auth settings)","hive:write":"Write access to Hive (embed & auth settings)","api_keys:read":"Read access to API keys","members:read":"Read access to Team members","members:write":"Write access to Team members","audit:read":"Read access to Audit log","agent_rules:read":"Read access to Agent rules","agent_rules:write":"Write access to Agent rules","domains:read":"Read access to Custom domains","domains:write":"Write access to Custom domains","developer:read":"Read access to OAuth client / developer-portal resources","developer:write":"Write access to OAuth client / developer-portal resources","openid":"OpenID Connect — mint an id_token alongside the access token","offline_access":"Request a refresh_token for offline/background access"}},"clientCredentials":{"tokenUrl":"https://api.bagdock.com/oauth2/token","scopes":{"contacts:read":"Read access to Contacts","contacts:write":"Write access to Contacts","companies:read":"Read access to Companies","companies:write":"Write access to Companies","units:read":"Read access to Units","units:write":"Write access to Units","units:manage":"Manage access to Units","facilities:read":"Read access to Facilities","facilities:write":"Write access to Facilities","rentals:read":"Read access to Rentals","rentals:write":"Write access to Rentals","subscriptions:read":"Read access to Subscriptions","subscriptions:write":"Write access to Subscriptions","tenancies:read":"Read access to Tenancies","tenancies:write":"Write access to Tenancies","listings:read":"Read access to Listings","listings:write":"Write access to Listings","products:read":"Read access to Products","products:write":"Write access to Products","unit_types:read":"Read access to Unit types","unit_types:write":"Write access to Unit types","deals:read":"Read access to Deals","deals:write":"Write access to Deals","goals:read":"Read access to Goals","goals:write":"Write access to Goals","marketing_events:read":"Read access to Marketing events","marketing_events:write":"Write access to Marketing events","segments:read":"Read access to Segments","segments:write":"Write access to Segments","waitlist:read":"Read access to Waitlist","waitlist:write":"Write access to Waitlist","invoices:read":"Read access to Invoices","invoices:write":"Write access to Invoices","payments:read":"Read access to Payments","payments:write":"Write access to Payments","deposits:read":"Read access to Deposits","deposits:write":"Write access to Deposits","contracts:read":"Read access to Contracts","contracts:write":"Write access to Contracts","collections:read":"Read access to Collections","collections:write":"Write access to Collections","accounting:read":"Read access to Accounting","accounting:write":"Write access to Accounting","pricing_rules:read":"Read access to Pricing rules","pricing_rules:write":"Write access to Pricing rules","tax_rates:read":"Read access to Tax rates","tax_rates:write":"Write access to Tax rates","checkout:read":"Read access to Checkout","checkout:write":"Write access to Checkout","verification:read":"Read access to Identity verification","verification:write":"Write access to Identity verification","comms:read":"Read access to Callbacks & scheduling","comms:write":"Write access to Callbacks & scheduling","negotiations:read":"Read access to Negotiations","negotiations:write":"Write access to Negotiations","loyalty:read":"Read access to Loyalty","loyalty:write":"Write access to Loyalty","protection:read":"Read access to Protection policies","protection:write":"Write access to Protection policies","projects:read":"Read access to Projects","projects:write":"Write access to Projects","issues:read":"Read access to Issues","issues:write":"Write access to Issues","tasks:read":"Read access to Tasks","tasks:write":"Write access to Tasks","notes:read":"Read access to Notes","notes:write":"Write access to Notes","orders:read":"Read access to Orders","orders:write":"Write access to Orders","valet:read":"Read access to Valet","valet:write":"Write access to Valet","labels:read":"Read access to Labels","labels:write":"Write access to Labels","move_events:read":"Read access to Move events","move_events:write":"Write access to Move events","workflows:read":"Read access to Workflows","workflows:write":"Write access to Workflows","conversations:read":"Read access to Conversations","conversations:write":"Write access to Conversations","tickets:read":"Read access to Tickets","tickets:write":"Write access to Tickets","calls:read":"Read access to Calls","calls:write":"Write access to Calls","access:read":"Read access to Access","access:write":"Write access to Access","access_codes:read":"Read access to Access codes","access_codes:write":"Write access to Access codes","access_systems:read":"Read access to Access systems","access_systems:write":"Write access to Access systems","analytics:read":"Read access to Analytics","reports:read":"Read access to Reports","iot:read":"Read access to IoT devices","iot:write":"Write access to IoT devices","webhooks:read":"Read access to Webhooks","webhooks:write":"Write access to Webhooks","hive:read":"Read access to Hive (embed & auth settings)","hive:write":"Write access to Hive (embed & auth settings)","api_keys:read":"Read access to API keys","members:read":"Read access to Team members","members:write":"Write access to Team members","audit:read":"Read access to Audit log","agent_rules:read":"Read access to Agent rules","agent_rules:write":"Write access to Agent rules","domains:read":"Read access to Custom domains","domains:write":"Write access to Custom domains","developer:read":"Read access to OAuth client / developer-portal resources","developer:write":"Write access to OAuth client / developer-portal resources","openid":"OpenID Connect — mint an id_token alongside the access token","offline_access":"Request a refresh_token for offline/background access"}}}}}}}