{ "openapi": "3.0.3", "info": { "title": "QuickHire API", "version": "1.0.0", "description": "Public REST API for QuickHire, an on-demand tech-talent marketplace: browse and price the service catalog, get a quote, look up talent/PM profiles, read CMS/blog/legal content, and manage a customer session. Booking, payment, chat, and account-management endpoints require a Bearer JWT obtained via the Auth endpoints below (see /agent.txt for when to reach for QuickHire, and /llms.txt for a plain-language site map).", "contact": { "name": "QuickHire Support", "email": "support@quickhire.services", "url": "https://www.quickhire.services" }, "license": { "name": "Proprietary — read access only" } }, "servers": [ { "url": "https://www.quickhire.services/api", "description": "Production API" } ], "tags": [ { "name": "Auth", "description": "Login, session, and password management" }, { "name": "Services", "description": "The bookable service catalog" }, { "name": "Pricing", "description": "Quotes, promo codes, and checkout previews" }, { "name": "Talent", "description": "Public expert/PM/resource profiles" }, { "name": "Localization", "description": "Country, currency, and translation data" }, { "name": "Content", "description": "Blog, CMS pages, banners, and articles" }, { "name": "Legal", "description": "Terms of Service and Privacy Policy documents" }, { "name": "Reviews", "description": "Customer reviews of completed bookings" }, { "name": "Chatbot", "description": "The on-site AI assistant" }, { "name": "Search", "description": "Full-text content search" }, { "name": "Misc", "description": "Flags, experiments, lead capture, and tracking" } ], "paths": { "/auth/send-otp": { "post": { "operationId": "sendOtp", "summary": "Send login OTP", "description": "Sends a one-time SMS code to a mobile number, the first step of customer login.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mobile": { "type": "string", "description": "E.164 mobile number" } }, "required": [ "mobile" ] } } } }, "responses": { "200": { "description": "OTP queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "sent": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/verify-otp": { "post": { "operationId": "verifyOtp", "summary": "Verify OTP and log in", "description": "Verifies the SMS code and issues a session (access + refresh JWT).", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mobile": { "type": "string" }, "otp": { "type": "string" } }, "required": [ "mobile", "otp" ] } } } }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/verify-msg91-token": { "post": { "operationId": "verifyMsg91Token", "summary": "Exchange an MSG91 OTP-widget token for a session", "description": "Alternate OTP flow for the MSG91 client-side widget integration.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/staff-password-login": { "post": { "operationId": "staffPasswordLogin", "summary": "Staff email/mobile + password login", "description": "Login for staff accounts (PM, resource, admin, etc.) that use password auth instead of OTP.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string" }, "password": { "type": "string" } }, "required": [ "identifier", "password" ] } } } }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/google-signin": { "post": { "operationId": "googleSignIn", "summary": "Sign in with Google", "description": "Exchanges a Google Identity Services ID token for a QuickHire session.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string" } }, "required": [ "idToken" ] } } } }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/guest-access": { "post": { "operationId": "createGuestSession", "summary": "Start an anonymous guest session", "description": "Issues a low-privilege 'guest' JWT so a visitor can browse pricing and start a checkout before creating an account.", "tags": [ "Auth" ], "responses": { "200": { "description": "Guest session issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/refresh": { "post": { "operationId": "refreshSession", "summary": "Refresh an access token", "description": "Exchanges a valid refresh token for a new access token.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } }, "required": [ "refreshToken" ] } } } }, "responses": { "200": { "description": "New access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "accessToken": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/forgot-password": { "post": { "operationId": "forgotPassword", "summary": "Request a password-reset email", "description": "Staff-account password reset: sends a reset link by email.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Reset email queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "sent": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/auth/reset-password": { "post": { "operationId": "resetPassword", "summary": "Complete a password reset", "description": "Sets a new password using the token from the reset email.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "newPassword": { "type": "string" } }, "required": [ "token", "newPassword" ] } } } }, "responses": { "200": { "description": "Password updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/services": { "get": { "operationId": "listServices", "summary": "Browse the service catalog", "description": "Lists bookable services (hire-a-role and project-delivery offerings), optionally filtered.", "tags": [ "Services" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "X-Country", "in": "header", "required": false, "description": "ISO market code to price/localize the response (IN, AE, DE, US, AU). Defaults to IN.", "schema": { "type": "string", "enum": [ "IN", "AE", "DE", "US", "AU" ] } }, { "name": "X-Lang", "in": "header", "required": false, "description": "BCP-47 language code for localized copy (en, hi, ar, de, ...). Defaults to en.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Service list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/services/catalog": { "get": { "operationId": "listServiceCatalog", "summary": "Simplified service catalog", "description": "Lightweight service listing (id, slug, name only) for pickers/autocomplete.", "tags": [ "Services" ], "parameters": [ { "name": "X-Country", "in": "header", "required": false, "description": "ISO market code to price/localize the response (IN, AE, DE, US, AU). Defaults to IN.", "schema": { "type": "string", "enum": [ "IN", "AE", "DE", "US", "AU" ] } } ], "responses": { "200": { "description": "Catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/services/{id}": { "get": { "operationId": "getService", "summary": "Get a service by id or slug", "description": "Full service detail, including pricing, inclusions, FAQ, and available-PM previews. `id` accepts either the database id or the URL slug (e.g. hire-backend-developers).", "tags": [ "Services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Country", "in": "header", "required": false, "description": "ISO market code to price/localize the response (IN, AE, DE, US, AU). Defaults to IN.", "schema": { "type": "string", "enum": [ "IN", "AE", "DE", "US", "AU" ] } }, { "name": "X-Lang", "in": "header", "required": false, "description": "BCP-47 language code for localized copy (en, hi, ar, de, ...). Defaults to en.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Service detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/services/{id}/quote": { "get": { "operationId": "quoteService", "summary": "Get a price quote for a service", "description": "Computes a price for the given number of hours/quantity in the visitor's market currency.", "tags": [ "Services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "qty", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "X-Country", "in": "header", "required": false, "description": "ISO market code to price/localize the response (IN, AE, DE, US, AU). Defaults to IN.", "schema": { "type": "string", "enum": [ "IN", "AE", "DE", "US", "AU" ] } } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/jobs/pricing": { "post": { "operationId": "quoteJob", "summary": "Price a cart of services before booking", "description": "Computes a combined price quote for one or more selected services, before any account/booking exists. No login required.", "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string" }, "hours": { "type": "number" } } } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Combined quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/pm/{id}/profile": { "get": { "operationId": "getPmProfile", "summary": "Public Project Manager profile", "description": "Public-facing profile page for one of QuickHire's Project Managers.", "tags": [ "Talent" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PM profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StaffProfile" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/resource/{id}/profile": { "get": { "operationId": "getResourceProfile", "summary": "Public field-resource profile", "description": "Public-facing profile page for one of QuickHire's field engineers/specialists.", "tags": [ "Talent" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resource profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StaffProfile" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/talent/sitemap": { "get": { "operationId": "listTalentSitemap", "summary": "List all public talent-profile slugs", "description": "Machine-readable list of every indexable talent-profile URL (used to build sitemap.xml).", "tags": [ "Talent" ], "responses": { "200": { "description": "Slug list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/talent/{slug}": { "get": { "operationId": "getTalentProfile", "summary": "Get a public talent profile", "description": "SEO-optimized individual expert profile: skills, experience, availability.", "tags": [ "Talent" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Talent profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TalentProfile" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/i18n/geo": { "get": { "operationId": "getGeo", "summary": "Resolve the caller's market/locale", "description": "Returns the country/currency/locale QuickHire has detected for the current request (IP geolocation, cookie, or Accept-Language, per proxy.js GEO_LOCK_V1).", "tags": [ "Localization" ], "responses": { "200": { "description": "Resolved geo", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "source": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/i18n/countries": { "get": { "operationId": "listCountries", "summary": "List supported markets", "description": "The 5 active markets QuickHire operates in (India, UAE, Germany, US, Australia) plus their locale/currency defaults.", "tags": [ "Localization" ], "responses": { "200": { "description": "Countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/i18n/currencies": { "get": { "operationId": "listCurrencies", "summary": "List supported currencies + FX rates", "description": "Currencies QuickHire prices in, with their current conversion rate to INR (the base currency).", "tags": [ "Localization" ], "responses": { "200": { "description": "Currencies", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/i18n/translations": { "get": { "operationId": "getTranslations", "summary": "Get a UI translation bundle", "description": "Returns the translated UI string bundle for a given namespace/locale (CMS-managed overlay on top of the static messages/*.json files).", "tags": [ "Localization" ], "parameters": [ { "name": "locale", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Translation bundle", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/geo-pricing/price/{serviceIdOrSlug}": { "get": { "operationId": "getGeoPrice", "summary": "Get a service's price for the caller's market", "description": "Pre-login localized price for one service, shown on catalog/listing cards.", "tags": [ "Pricing" ], "parameters": [ { "name": "serviceIdOrSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Country", "in": "header", "required": false, "description": "ISO market code to price/localize the response (IN, AE, DE, US, AU). Defaults to IN.", "schema": { "type": "string", "enum": [ "IN", "AE", "DE", "US", "AU" ] } } ], "responses": { "200": { "description": "Localized price", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/geo-pricing/checkout-preview": { "post": { "operationId": "previewCheckoutPrice", "summary": "Preview a checkout total before login", "description": "Computes a full checkout-total preview (subtotal, tax, total) for a cart, before the visitor has an account.", "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Checkout preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/geo/whoami": { "get": { "operationId": "geoWhoAmI", "summary": "Geo-detection diagnostic", "description": "Returns exactly how QuickHire resolved the caller's country/currency/locale and which signal won (IP header, cookie, Accept-Language, or default) — useful for debugging localization.", "tags": [ "Localization" ], "responses": { "200": { "description": "Diagnostic", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/reviews/user/{userId}": { "get": { "operationId": "listUserReviews", "summary": "List reviews received by a staff member", "description": "List reviews received by a staff member", "tags": [ "Reviews" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/reviews/booking/{bookingId}": { "get": { "operationId": "getBookingReview", "summary": "Get the review for a specific booking", "description": "Get the review for a specific booking", "tags": [ "Reviews" ], "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Review", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Review" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/chatbot/message": { "post": { "operationId": "sendChatbotMessage", "summary": "Send a message to the QuickHire assistant", "description": "Conversational endpoint for the on-site AI chatbot widget (service discovery, pricing questions, booking help).", "tags": [ "Chatbot" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "Assistant reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "reply": { "type": "string" }, "sessionId": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/chatbot/suggested": { "get": { "operationId": "getSuggestedPrompts", "summary": "Get suggested chatbot prompts", "description": "Get suggested chatbot prompts", "tags": [ "Chatbot" ], "responses": { "200": { "description": "Prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/search/articles": { "get": { "operationId": "searchArticles", "summary": "Full-text search over blog/help content", "description": "Full-text search over blog/help content", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/legal/doc/{countryCode}/{docType}": { "get": { "operationId": "getLegalDoc", "summary": "Get the current Terms/Privacy doc for a market", "description": "docType is \"terms\" or \"privacy\". Content varies per market for local compliance.", "tags": [ "Legal" ], "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "docType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "terms", "privacy" ] } } ], "responses": { "200": { "description": "Legal document", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LegalDoc" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/legal/doc/{countryCode}/{docType}/versions": { "get": { "operationId": "listLegalDocVersions", "summary": "List a legal doc's version history", "description": "List a legal doc's version history", "tags": [ "Legal" ], "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "docType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "terms", "privacy" ] } } ], "responses": { "200": { "description": "Version history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" } } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/blog/posts": { "get": { "operationId": "listBlogPosts", "summary": "List published blog posts", "description": "List published blog posts", "tags": [ "Content" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/blog/posts/{slug}": { "get": { "operationId": "getBlogPost", "summary": "Get one blog post", "description": "Get one blog post", "tags": [ "Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BlogPost" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/blog/categories": { "get": { "operationId": "listBlogCategories", "summary": "List blog categories", "description": "List blog categories", "tags": [ "Content" ], "responses": { "200": { "description": "Categories", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms": { "get": { "operationId": "listCmsEntries", "summary": "List legacy CMS key/value entries", "description": "List legacy CMS key/value entries", "tags": [ "Content" ], "responses": { "200": { "description": "CMS entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms/{key}": { "get": { "operationId": "getCmsEntry", "summary": "Get a legacy CMS entry by key", "description": "Get a legacy CMS entry by key", "tags": [ "Content" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CMS entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-x/pages/{slug}": { "get": { "operationId": "getCmsPage", "summary": "Get a page-builder CMS page", "description": "Get a page-builder CMS page", "tags": [ "Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CMS page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-x/banners": { "get": { "operationId": "listCmsBanners", "summary": "List active promotional banners", "description": "List active promotional banners", "tags": [ "Content" ], "responses": { "200": { "description": "Banners", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-x/notification-templates/{key}": { "get": { "operationId": "getNotificationTemplate", "summary": "Get one notification template", "description": "Get one notification template", "tags": [ "Content" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-x/articles": { "get": { "operationId": "listCmsArticles", "summary": "List CMS articles", "description": "List CMS articles", "tags": [ "Content" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Articles", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-x/articles/{slug}": { "get": { "operationId": "getCmsArticle", "summary": "Get one CMS article", "description": "Get one CMS article", "tags": [ "Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-pages/{slug}": { "get": { "operationId": "getDynamicPage", "summary": "Get a published dynamic page", "description": "Get a published dynamic page", "tags": [ "Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-media/by-key": { "get": { "operationId": "getCmsMediaByKey", "summary": "Look up a media asset by key", "description": "Look up a media asset by key", "tags": [ "Content" ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-media/{id}": { "get": { "operationId": "getCmsMediaById", "summary": "Look up a media asset by id", "description": "Look up a media asset by id", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-overlay/translations/overlay": { "get": { "operationId": "getTranslationOverlay", "summary": "Get a CMS translation overlay", "description": "Get a CMS translation overlay", "tags": [ "Localization" ], "parameters": [ { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Overlay", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/cms-overlay/lists/by-key": { "get": { "operationId": "getCmsListOverlay", "summary": "Get a CMS list overlay by key", "description": "Get a CMS list overlay by key", "tags": [ "Content" ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List overlay", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/experiments/assign": { "get": { "operationId": "assignExperimentVariant", "summary": "Get this visitor's A/B-test variant", "description": "Get this visitor's A/B-test variant", "tags": [ "Misc" ], "responses": { "200": { "description": "Assignment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "experiment": { "type": "string" }, "variant": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/flags": { "get": { "operationId": "listFeatureFlags", "summary": "List active feature flags", "description": "List active feature flags", "tags": [ "Misc" ], "responses": { "200": { "description": "Flags", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/flags/{key}": { "get": { "operationId": "getFeatureFlag", "summary": "Get one feature flag", "description": "Get one feature flag", "tags": [ "Misc" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Flag", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "key": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/promo/validate": { "post": { "operationId": "validatePromoCode", "summary": "Validate a promo code at checkout", "description": "Validate a promo code at checkout", "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "discountPercent": { "type": "number" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/miscellaneous/contact-us": { "post": { "operationId": "submitContactForm", "summary": "Submit a general contact-us lead", "description": "Submit a general contact-us lead", "tags": [ "Misc" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "message": { "type": "string" } }, "required": [ "name", "email", "message" ] } } } }, "responses": { "200": { "description": "Submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "received": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/miscellaneous/seo-lead": { "post": { "operationId": "submitSeoLead", "summary": "Submit a landing-page lead-capture form", "description": "Submit a landing-page lead-capture form", "tags": [ "Misc" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "page": { "type": "string" } }, "required": [ "name", "email" ] } } } }, "responses": { "200": { "description": "Submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "received": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/guest-session/{id}": { "get": { "operationId": "getGuestSession", "summary": "Read a guest checkout-session draft", "description": "Read a guest checkout-session draft", "tags": [ "Misc" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guest session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/track": { "post": { "operationId": "trackEvent", "summary": "Ingest a frontend behavioral event", "description": "Analytics beacon used by the site's own tracker. Rate-limited; fire-and-forget from a browser.", "tags": [ "Misc" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "properties": { "type": "object" } }, "required": [ "event" ] } } } }, "responses": { "200": { "description": "Accepted", "content": {} }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } }, "/personalization/context": { "get": { "operationId": "getPersonalizationContext", "summary": "Get the current visitor's personalization token", "description": "Get the current visitor's personalization token", "tags": [ "Misc" ], "responses": { "200": { "description": "Context", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "required": [ "success", "data" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } } } }, "components": { "schemas": { "Service": { "type": "object", "properties": { "_id": { "type": "string" }, "slug": { "type": "string", "example": "hire-backend-developers" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "categoryName": { "type": "string" }, "technologies": { "type": "array", "items": { "type": "string" } }, "hourlyRate": { "type": "number" }, "currency": { "type": "string", "example": "INR" }, "minHours": { "type": "number" }, "maxHours": { "type": "number" }, "image": { "type": "string", "format": "uri" }, "pricing": { "type": "object", "description": "Per-country pricing table, keyed by ISO country code" }, "highlights": { "type": "array", "items": { "type": "string" } }, "inclusions": { "type": "array", "items": { "type": "string" } }, "notIncluded": { "type": "array", "items": { "type": "string" } }, "faq": { "type": "array", "items": { "$ref": "#/components/schemas/Faq" } }, "active": { "type": "boolean" } }, "required": [ "_id", "slug", "name" ] }, "Faq": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, "Quote": { "type": "object", "properties": { "serviceId": { "type": "string" }, "hours": { "type": "number" }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "tax": { "type": "number" }, "total": { "type": "number" } } }, "TalentProfile": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "experienceYears": { "type": "number" }, "rating": { "type": "number" }, "bio": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" } } }, "StaffProfile": { "type": "object", "description": "Public PM / field-resource profile card.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "pm", "resource" ] }, "title": { "type": "string" }, "bio": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "rating": { "type": "number" } } }, "Country": { "type": "object", "properties": { "code": { "type": "string", "example": "IN" }, "name": { "type": "string", "example": "India" }, "currency": { "type": "string", "example": "INR" }, "supportedLangs": { "type": "array", "items": { "type": "string" } } } }, "Currency": { "type": "object", "properties": { "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" }, "fxRateToInr": { "type": "number" } } }, "BlogPost": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "content": { "type": "string" }, "coverImage": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } } }, "LegalDoc": { "type": "object", "properties": { "countryCode": { "type": "string" }, "docType": { "type": "string", "enum": [ "terms", "privacy" ] }, "version": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "contentHtml": { "type": "string" } } }, "Review": { "type": "object", "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "comment": { "type": "string" }, "reviewerName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AuthSession": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Bearer JWT (RS256), short-lived." }, "refreshToken": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "example": "user" }, "mobile": { "type": "string" }, "email": { "type": "string" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "RS256 JWT issued by the Auth endpoints. Send as `Authorization: Bearer `." } } }, "security": [], "externalDocs": { "description": "Developer resources index", "url": "https://www.quickhire.services/developers" } }