{ "openapi": "3.1.0", "info": { "title": "WellFred API", "version": "1.0.0", "description": "Public WellFred discovery, guest RFQs and booking intents. Read https:\/\/app.wellfred.com\/agents.md for workflows and examples. Booking intents require email verification on WellFred before a booking request is sent." }, "servers": [ { "url": "https:\/\/app.wellfred.com\/api\/agent" } ], "paths": { "\/search": { "post": { "operationId": "agent.search", "summary": "Search or browse ranked offerings using the marketplace search engine.\nSupply structured constraints alongside natural-language service text.\nA date checks the schedule, not capacity for a party. Prices are in the\noffering's own currency; budget filters never compare unlike currencies", "tags": [ "WellFred public API" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AgentSearchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string" }, "providerUuid": { "type": "string" }, "providerName": { "type": "string" }, "title": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "priceUnit": { "type": "string" }, "pricingType": { "type": "string" }, "delivery": { "type": "string" }, "schedulingMode": { "type": "string" }, "nextAction": { "type": "string", "enum": [ "choose_option_on_website", "prepare_booking_intent" ] }, "url": { "type": "string" } }, "required": [ "serviceId", "providerUuid", "providerName", "title", "price", "currency", "priceUnit", "pricingType", "delivery", "schedulingMode", "nextAction", "url" ] } }, "recommendation": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "No matching offerings in this search. Broaden the filters or request quotes." ] } ] }, "availabilityChecked": { "type": "string" }, "partySize": { "type": "integer" }, "notice": { "type": "string", "const": "Schedule checks do not guarantee capacity for a party. Starting prices are estimates; priceUnit describes what the price covers. In-home service areas must be confirmed for the exact address." } }, "required": [ "success", "message", "results", "recommendation", "availabilityChecked", "partySize", "notice" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/rfq\/questions": { "post": { "operationId": "agent.rfq.questions", "summary": "Get the questions for a quote request. Labels\/types come only from the saved\nquestion set; the model may submit values by key but never author labels", "tags": [ "WellFred public API" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "subcategoryUuid": { "type": [ "string", "null" ], "format": "uuid" }, "serviceUuid": { "type": [ "string", "null" ], "format": "uuid" }, "requestedService": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 500 }, "locale": { "type": [ "string", "null" ], "enum": [ "en", "es", null ] } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "available": { "type": "boolean" }, "categoryUuid": { "type": [ "string", "null" ] }, "subcategoryUuid": { "type": "string" }, "questionSetUuid": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label_en": { "type": "string" }, "label_es": { "type": "string" } }, "required": [ "value", "label_en", "label_es" ] } } }, "required": [ "key", "type", "label", "required", "options" ] } } }, "required": [ "success", "message", "available", "categoryUuid", "subcategoryUuid", "questionSetUuid", "questions" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "success", "message", "available" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/locations": { "get": { "operationId": "agent.locations", "summary": "Resolve a location to coordinates; return candidates rather than guess", "tags": [ "WellFred public API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameEs": { "type": "string" }, "province": { "type": "string" }, "lat": { "type": "number", "description": "zones.center_lat\/lng are NOT NULL decimals cast to float \u2014\na zone always knows where it is." }, "lng": { "type": "number" } }, "required": [ "id", "name", "nameEs", "province", "lat", "lng" ] } } }, "required": [ "success", "message", "locations" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/categories": { "get": { "operationId": "agent.categories", "summary": "Browse the service taxonomy without a natural-language search", "tags": [ "WellFred public API" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameEs": { "type": "string" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameEs": { "type": "string" } }, "required": [ "id", "name", "nameEs" ] } } }, "required": [ "id", "name", "nameEs", "subcategories" ] } } }, "required": [ "success", "message", "categories" ] } } } } } } }, "\/providers": { "get": { "operationId": "agent.providers", "description": "Response: { providers: [ { id, name, category, subcategory?, description?,\n imageUrl?, priceFrom?, distanceKm?, rating? } ] }\nOnly id\/name\/category are guaranteed; the rest are null when the schema\nhas no data for a row. Defaults to 25 providers; limit accepts up to 500.\n\ncategory\/subcategory are the slugs of the provider's first custom-service\ncategory and subcategory (Str::slug(name_en)); category is \"other\" when no\nservices exist, subcategory is null when the first service has none. The\nsubcategory helps distinguish services because the top-level taxonomy\nis coarse (private chefs share the \"house-home\" category with cleaners).\npriceFrom is the lowest getBasePrice() across all the provider's services.\nrating is the 0\u20135 star normalised fred_score (same formula as searchServices).\ndistanceKm is haversine distance from the supplied lat\/lng; null when absent.", "summary": "Provider catalog for villa-tablet browse overlay + featured carousel.\nReturns validated providers ordered best-first for the given coordinates\n(nearest first when coords provided, rating-desc fallback when absent)", "tags": [ "WellFred public API" ], "parameters": [ { "name": "lat", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 } }, { "name": "limit", "in": "query", "description": "Maximum providers to return (default 25, up to 500).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": [ "string", "null" ] }, "categoryName": { "type": [ "string", "null" ] }, "categoryNameEs": { "type": [ "string", "null" ] }, "subcategoryName": { "type": [ "string", "null" ] }, "subcategoryNameEs": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "distanceKm": { "type": [ "number", "null" ] }, "rating": { "type": [ "number", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "serviceName": { "type": [ "string", "null" ] }, "serviceNameEs": { "type": [ "string", "null" ] }, "subcategoryName": { "type": [ "string", "null" ] }, "subcategoryNameEs": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] } }, "required": [ "title", "serviceName", "serviceNameEs", "subcategoryName", "subcategoryNameEs", "priceFrom", "currency" ] } } }, "required": [ "id", "name", "category", "subcategory", "categoryName", "categoryNameEs", "subcategoryName", "subcategoryNameEs", "description", "imageUrl", "priceFrom", "currency", "distanceKm", "rating", "services" ] } } }, "required": [ "success", "message", "providers" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/providers\/search": { "get": { "operationId": "agent.providers.search", "description": "Query mode merges deterministic business-name matches ahead of semantic\nservice matches. ID mode resolves authoritative card snapshots without\ninvoking semantic search.", "summary": "Search providers by name or service need, or resolve known provider IDs", "tags": [ "WellFred public API" ], "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 120 } }, { "name": "ids[]", "in": "query", "schema": { "type": "array", "format": "uuid", "items": { "type": "string", "format": "uuid" } } }, { "name": "lat", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": [ "string", "null" ] }, "categoryName": { "type": [ "string", "null" ] }, "categoryNameEs": { "type": [ "string", "null" ] }, "subcategoryName": { "type": [ "string", "null" ] }, "subcategoryNameEs": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "distanceKm": { "type": [ "number", "null" ] }, "rating": { "type": [ "number", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "serviceName": { "type": [ "string", "null" ] }, "serviceNameEs": { "type": [ "string", "null" ] }, "subcategoryName": { "type": [ "string", "null" ] }, "subcategoryNameEs": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] } }, "required": [ "title", "serviceName", "serviceNameEs", "subcategoryName", "subcategoryNameEs", "priceFrom", "currency" ] } } }, "required": [ "id", "name", "category", "subcategory", "categoryName", "categoryNameEs", "subcategoryName", "subcategoryNameEs", "description", "imageUrl", "priceFrom", "currency", "distanceKm", "rating", "services" ] } } }, "required": [ "success", "message", "providers" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/providers\/profile": { "post": { "operationId": "agent.providers.profile", "description": "Filters: only validated provider profiles are exposed. A pending or\nblocked status returns the same 404 as a missing uuid \u2014 the agent\nhas no use case for unreviewed providers and we don't leak status.", "summary": "Provider profile (read-only). Returns just the fields the agent needs\nto answer follow-up questions (\"does this provider speak English?\",\n\"how long have they been on Wellfred?\", \"what languages?\") without\nhaving to scrape the public site or guess", "tags": [ "WellFred public API" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "providerUuid": { "type": "string" } }, "required": [ "providerUuid" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "providerUuid": { "type": "string" }, "businessName": { "type": [ "string", "null" ] }, "bio": { "type": [ "string", "null" ] }, "locationType": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "hoursOfOperation": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] } } ] } }, "refundPolicy": { "type": [ "string", "null" ] }, "memberSinceIso": { "type": "string", "description": "memberSinceIso lets the agent answer \"how long on Wellfred?\"." }, "url": { "type": "string", "description": "Public provider page so Fred can share a link." } }, "required": [ "success", "message", "providerUuid", "businessName", "bio", "locationType", "city", "country", "hoursOfOperation", "refundPolicy", "memberSinceIso", "url" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "csrf_token": { "type": [ "string", "null" ] }, "error_code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "success", "message", "csrf_token" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/availability": { "post": { "operationId": "agent.availability", "summary": "Real availability for a service on a date. Read-only", "tags": [ "WellFred public API" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string" }, "date": { "type": "string", "format": "date" } }, "required": [ "serviceId", "date" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "startIso": { "type": "string" }, "endIso": { "type": "string" }, "label": { "type": "string" } }, "required": [ "startIso", "endIso", "label" ] } } }, "required": [ "success", "message", "slots" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "slots": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "slots" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/rfqs": { "post": { "operationId": "agent.rfqs", "summary": "Submit an account-free quote request. Reuse the idempotency key on retries.\nSuccess starts provider follow-up; it does not confirm a booking", "tags": [ "WellFred public API" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "sourceChannel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "web", "tablet", null ] }, "categoryUuid": { "type": [ "string", "null" ], "format": "uuid" }, "subcategoryUuid": { "type": [ "string", "null" ], "format": "uuid" }, "serviceUuid": { "type": [ "string", "null" ], "format": "uuid" }, "requestedService": { "type": [ "string", "null" ], "maxLength": 500 }, "preferredProviderUuid": { "type": [ "string", "null" ], "format": "uuid" }, "contactName": { "type": "string", "maxLength": 160 }, "contactPhoneCountryCode": { "type": "string", "maxLength": 10 }, "contactPhoneNumber": { "type": "string", "maxLength": 30 }, "contactEmail": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "locale": { "type": [ "string", "null" ], "enum": [ "en", "es", null ] }, "location": { "type": [ "string", "null" ], "maxLength": 1000 }, "timing": { "type": [ "string", "null" ], "maxLength": 500 }, "budget": { "type": [ "number", "null" ], "minimum": 0 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "answers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "maxItems": 20 }, "idempotencyKey": { "type": [ "string", "null" ], "maxLength": 120 }, "budgetCurrency": { "type": [ "string", "null" ] } }, "required": [ "contactName", "contactPhoneCountryCode", "contactPhoneNumber" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "rfqUuid": { "type": "string" }, "reference": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "success", "message", "rfqUuid", "reference", "created" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/booking-intents": { "post": { "operationId": "agent.booking-intents", "summary": "Prepare an expiring request. The confirmation link requires verified email before booking", "tags": [ "WellFred public API" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "startIso": { "type": "string", "format": "date-time" }, "partySize": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "origin": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } } } }, "required": [ "serviceId", "startIso" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "intentId": { "type": "string" }, "confirmUrl": { "type": "string" }, "readback": { "type": "object", "properties": { "provider": { "type": "string" }, "service": { "type": "string" }, "startIso": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "partySize": { "type": "integer" }, "priceUnit": { "type": "string" }, "pricingType": { "type": "string" } }, "required": [ "provider", "service", "startIso", "price", "currency", "partySize", "priceUnit", "pricingType" ] } }, "required": [ "success", "message", "intentId", "confirmUrl", "readback" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "schemas": { "AgentSearchRequest": { "type": "object", "properties": { "query": { "type": [ "string", "null" ], "maxLength": 500 }, "categoryHint": { "type": [ "string", "null" ], "maxLength": 120 }, "categoryUuid": { "type": [ "string", "null" ], "format": "uuid" }, "subcategoryUuid": { "type": [ "string", "null" ], "format": "uuid" }, "lat": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "lng": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "delivery": { "type": [ "string", "null" ], "enum": [ "in-home", "on-location", null ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "partySize": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "maxPrice": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": [ "string", "null" ], "description": "Kept in step with what an offering can actually be priced in \/\nmeasured by, so a filter can name every real value rather than\nsilently hiding the units it forgot.", "enum": [ "USD", "CRC", null ] }, "priceUnit": { "type": [ "string", "null" ], "enum": [ "session", "hour", "day", "kg", "km", "liter", "item", "person", null ] }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, "title": "AgentSearchRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }