{ "openapi": "3.1.0", "info": { "title": "Beezybee API", "description": "Public REST API for the Beezybee local service marketplace and Borrowbee item lending platform in Karlsruhe, Germany. Designed for AI agents, developers, and integration partners.", "version": "1.1.0", "contact": { "name": "Beezybee Support", "url": "https://beezybee-app.de/support" } }, "servers": [ { "url": "https://europe-west3-gethelperbeecom.cloudfunctions.net/api", "description": "Production (europe-west3)" } ], "paths": { "/v1/jobs": { "get": { "operationId": "searchJobs", "summary": "Search for available jobs", "description": "Find open job requests for local help in the Karlsruhe area. Use when a user needs to find a helper for gardening, cleaning, moving, repairs, childcare, pet care, shopping, or events.", "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number", "default": 49.0069 }, "description": "Latitude of search center" }, { "name": "lng", "in": "query", "schema": { "type": "number", "default": 8.4037 }, "description": "Longitude of search center" }, { "name": "radius", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 50 }, "description": "Search radius in km" }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["GARDENING", "CLEANING", "MOVING", "TECH_REPAIR", "CHILDCARE", "PETCARE", "SHOPPING", "EVENTS", "BORROWING", "OTHER"] }, "description": "Filter by category" }, { "name": "budget_min", "in": "query", "schema": { "type": "number" }, "description": "Minimum price in EUR" }, { "name": "budget_max", "in": "query", "schema": { "type": "number" }, "description": "Maximum price in EUR" }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter by desired date (YYYY-MM-DD)" }, { "name": "urgent", "in": "query", "schema": { "type": "boolean" }, "description": "Only urgent jobs" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "price_asc", "price_desc", "distance"], "default": "newest" }, "description": "Sort order" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "List of matching jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get job details", "description": "Retrieve full details for a specific job by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job ID" } ], "responses": { "200": { "description": "Job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/listings": { "get": { "operationId": "searchListings", "summary": "Search Borrowbee listings", "description": "Find items available for borrowing or renting near a location. Use when a user wants to borrow tools, electronics, camping gear, or other items.", "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number", "default": 49.0069 } }, { "name": "lng", "in": "query", "schema": { "type": "number", "default": 8.4037 } }, { "name": "radius", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 50 } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["GARDENING", "CLEANING", "MOVING", "TECH_REPAIR", "CHILDCARE", "PETCARE", "SHOPPING", "EVENTS", "BORROWING", "OTHER"] } }, { "name": "price_max", "in": "query", "schema": { "type": "number" }, "description": "Max price per day in EUR" }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": ["new", "like_new", "good", "fair"] } }, { "name": "instant_booking", "in": "query", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "price_asc", "price_desc", "distance"], "default": "newest" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of matching listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } } }, "/v1/listings/{id}": { "get": { "operationId": "getListing", "summary": "Get listing details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listing details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } } } } }, "/v1/categories": { "get": { "operationId": "getCategories", "summary": "Get all service categories", "description": "Returns all available service and borrowing categories with price ranges. Use to understand what Beezybee offers.", "parameters": [ { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["de", "en"], "default": "en" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["service", "borrowing"] } } ], "responses": { "200": { "description": "List of categories" } } } }, "/v1/estimate": { "get": { "operationId": "getPriceEstimate", "summary": "Get price estimate for a service", "description": "Returns a price range estimate based on category, duration, and local market data. Use before suggesting a budget to the user.", "parameters": [ { "name": "category", "in": "query", "required": true, "schema": { "type": "string", "enum": ["GARDENING", "CLEANING", "MOVING", "TECH_REPAIR", "CHILDCARE", "PETCARE", "SHOPPING", "EVENTS", "BORROWING", "OTHER"] } }, { "name": "duration_hours", "in": "query", "schema": { "type": "number", "default": 1 } }, { "name": "helpers", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "lat", "in": "query", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Price estimate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } } } } }, "/v1/helpers/availability": { "get": { "operationId": "checkAvailability", "summary": "Check helper availability", "description": "See how many verified helpers are available for a category near a given location. Use to assess if a job is likely to be fulfilled quickly.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "schema": { "type": "number", "default": 49.0069 } }, { "name": "lng", "in": "query", "schema": { "type": "number", "default": 8.4037 } }, { "name": "radius", "in": "query", "schema": { "type": "number", "default": 50 } }, { "name": "min_reliability", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 100 } } ], "responses": { "200": { "description": "Availability summary with top helpers" } } } }, "/v1/stats": { "get": { "operationId": "getStats", "summary": "Get platform statistics", "description": "Returns live platform statistics including coverage, categories, pricing, and capabilities.", "responses": { "200": { "description": "Platform statistics" } } } } }, "components": { "schemas": { "Job": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": ["GARDENING", "CLEANING", "MOVING", "TECH_REPAIR", "CHILDCARE", "PETCARE", "SHOPPING", "EVENTS", "BORROWING", "OTHER"] }, "type": { "type": "string", "const": "beezybee" }, "status": { "type": "string" }, "price_eur": { "type": "number" }, "price_range": { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "description": "AI-estimated price range in EUR (±20% of base price)" }, "location": { "$ref": "#/components/schemas/Location" }, "desired_at": { "type": "string", "format": "date-time", "nullable": true }, "deadline": { "type": "string", "format": "date-time", "nullable": true, "description": "Job deadline (max 30 days for commercial users)" }, "time_preference": { "type": "string", "enum": ["vormittags", "nachmittags", "abends", "wochenende", "flexibel"], "nullable": true }, "urgent": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "helpers_needed": { "type": "integer", "maximum": 4 }, "applications_count": { "type": "integer" }, "max_applicants": { "type": "integer", "description": "Dynamic: helpers_needed * 3" }, "smart_eta_minutes": { "type": "integer", "nullable": true }, "photos": { "type": "array", "items": { "type": "string" }, "description": "Photo URLs" }, "requires_license": { "type": "boolean" }, "express": { "type": "boolean" }, "remote_task": { "type": "boolean" }, "pricing_confidence": { "type": "string", "enum": ["low", "medium", "high"], "nullable": true } } }, "Listing": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "type": { "type": "string", "const": "borrowbee" }, "status": { "type": "string" }, "price_per_day_eur": { "type": "number" }, "price_per_week_eur": { "type": "number", "nullable": true }, "deposit_eur": { "type": "number" }, "condition": { "type": "string", "enum": ["new", "like_new", "good", "fair"] }, "location": { "$ref": "#/components/schemas/Location" }, "instant_booking": { "type": "boolean" }, "photos": { "type": "array", "items": { "type": "string" } }, "owner_reliability": { "$ref": "#/components/schemas/ReliabilityScore" } } }, "Location": { "type": "object", "properties": { "city": { "type": "string" }, "plz": { "type": "string", "description": "Postal code (PLZ)" }, "district": { "type": "string", "nullable": true, "description": "City district/Stadtteil" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "distance_km": { "type": "number" } } }, "ReliabilityScore": { "type": "object", "description": "Helper reliability metrics. Score range: 0-100. Recommend filtering for score > 80 for time-sensitive tasks.", "properties": { "reliability_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "completed_jobs": { "type": "integer" }, "avg_response_minutes": { "type": "integer" }, "cancellation_rate": { "type": "number" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "verified": { "type": "boolean" } } }, "Estimate": { "type": "object", "properties": { "category": { "type": "string" }, "price_estimate_eur": { "type": "number" }, "price_min_eur": { "type": "number" }, "price_max_eur": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "based_on_jobs": { "type": "integer" }, "currency": { "type": "string", "const": "EUR" } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable message" }, "suggestion": { "type": "string", "description": "What the agent should do next" }, "alternatives": { "type": "array" }, "alternatives_count": { "type": "integer" } } } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional API key for higher rate limits. Without key: 20 req/min. With key: 100 req/min." } } }, "security": [ {}, { "ApiKey": [] } ] }