{"openapi":"3.1.0","info":{"title":"Ventcare Provider API","version":"1.0.0","description":"Read your own Ventcare listing, services, availability and bookings, and move visits through their lifecycle. Every key is scoped to a single listing. Ventcare's commission, payout and tax figures are never returned.","contact":{"name":"Ventcare support","email":"sales@ventcare.org","url":"https://ventcare.org/developers"}},"servers":[{"url":"https://ventcare.org","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your provider API key, e.g. `Authorization: Bearer vc_live_...`."}},"schemas":{"Booking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"listing_id":{"type":"string","format":"uuid"},"service":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"duration_minutes":{"type":"integer","nullable":true}}},"scheduled_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","confirmed","completed","cancelled"]},"payment_status":{"type":"string","example":"paid"},"amount":{"type":"number","description":"Amount the client pays, in KES."},"currency":{"type":"string","example":"KES"},"session_mode":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"client":{"type":"object","description":"Phone and email are null until the client's payment has cleared.","properties":{"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/api/public/v1/listing":{"get":{"summary":"Your listing","description":"Scope required: `listing:read`.","responses":{"200":{"description":"Listing summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/public/v1/services":{"get":{"summary":"Your session types","description":"Scope required: `services:read`.","responses":{"200":{"description":"Services","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/public/v1/availability":{"get":{"summary":"Your weekly hours and blocked periods","description":"Scope required: `availability:read`.","responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"hours":{"type":"array","items":{"type":"object"}},"blocks":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/public/v1/bookings":{"get":{"summary":"List your bookings","description":"Scope required: `bookings:read`.","parameters":[{"name":"from","in":"query","description":"ISO timestamp — only bookings scheduled at or after this moment.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"ISO timestamp — only bookings scheduled at or before this moment.","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","confirmed","completed","cancelled"]}},{"name":"limit","in":"query","description":"Default 50, maximum 200.","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Bookings ordered by appointment time","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/public/v1/bookings/{id}":{"get":{"summary":"One booking","description":"Scope required: `bookings:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Booking"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/public/v1/bookings/{id}/status":{"post":{"summary":"Update a visit's status","description":"Scope required: `bookings:write`. Money, payment state and client ownership are not writable.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","confirmed","completed","cancelled"]}}}}}},"responses":{"200":{"description":"Updated booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Booking"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}