{"openapi":"3.1.0","info":{"title":"SalesRepsForHire.com Public API","version":"1.0.0","summary":"Lead intake, WebMCP tool surface, and operational endpoints for the on-demand sales-talent marketplace.","description":"All endpoints are public and rate-limited per IP. Machine clients should prefer the WebMCP tool surface (/mcp, JSON-RPC 2.0) for read access; /api/leads is the single intake for all marketplace forms. No authentication is currently required; identity (OAuth 2.1 / OIDC) is planned.","contact":{"name":"SalesRepsForHire.com","url":"https://salesrepsforhire.com"}},"servers":[{"url":"https://salesrepsforhire.com"}],"paths":{"/api/leads":{"post":{"operationId":"submitLead","summary":"Single intake for all marketplace forms","description":"Writes to the shared talent-network backend. Rate limit: 10 requests/minute per IP; 429 responses include Retry-After.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["employer_request","opportunity","rep_early_access"],"description":"Discriminates the data payload shape."},"data":{"oneOf":[{"type":"object","title":"employer_request data","properties":{"contactName":{"type":"string","maxLength":120},"contactEmail":{"type":"string","maxLength":200,"format":"email"},"contactPhone":{"type":"string","maxLength":40},"provider":{"type":"string","maxLength":500,"description":"What the employer sells."},"market":{"type":"string","maxLength":200,"description":"Target geography."},"headcount":{"type":"string","maxLength":20},"timeline":{"type":"string","maxLength":120},"housing":{"type":"string","maxLength":120}},"required":["contactName","contactEmail","contactPhone","provider","market"]},{"type":"object","title":"opportunity data","properties":{"title":{"type":"string","maxLength":200},"companyName":{"type":"string","maxLength":200},"contactEmail":{"type":"string","maxLength":200,"format":"email"},"description":{"type":"string","maxLength":4000},"market":{"type":"string","maxLength":200},"provider":{"type":"string","maxLength":300},"employerType":{"type":"string","maxLength":120},"employmentType":{"type":"string","maxLength":120},"headcountNeeded":{"type":"integer","minimum":1,"maximum":1000},"housingProvided":{"type":"boolean"},"paySchedule":{"type":"string","maxLength":120},"paymentTrigger":{"type":"string","maxLength":300},"perInstall":{"type":"number","minimum":0},"role":{"type":"string","maxLength":120},"salesChannel":{"type":"string","maxLength":120},"state":{"type":"string","maxLength":60},"requirements":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":10},"startDate":{"type":"string","maxLength":60}},"required":["title","companyName","contactEmail","description","market"]},{"type":"object","title":"rep_early_access data","properties":{"email":{"type":"string","maxLength":200,"format":"email"}},"required":["email"]}]}},"required":["kind","data"]}}}},"responses":{"201":{"description":"Lead accepted into the talent network.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string"}},"required":["ok","id"]}}}},"400":{"description":"Validation failure.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["ok","error"]}}}},"429":{"description":"Rate limit exceeded (includes Retry-After header).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["ok","error"]}}}},"502":{"description":"Talent-network backend rejected the write.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["ok","error"]}}}},"503":{"description":"Intake not configured (missing backend URL).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["ok","error"]}}}}}}},"/mcp":{"get":{"operationId":"mcpDescriptor","summary":"WebMCP server descriptor (tools, protocol version, usage examples)","responses":{"200":{"description":"Descriptor document.","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"mcpRpc","summary":"WebMCP JSON-RPC 2.0 endpoint","description":"Methods: initialize, tools/list, tools/call, ping. Protocol version 2024-11-05. Rate limit: 60 requests/minute per IP. Discovery: /.well-known/mcp.json.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["integer","string"]},"method":{"type":"string","enum":["initialize","tools/list","tools/call","ping","notifications/initialized"]},"params":{"type":"object","properties":{"name":{"type":"string","enum":["search_sales_reps","list_open_opportunities","estimate_workforce","get_market_intelligence","list_directory_pages"]},"arguments":{"type":"object"}}}},"required":["jsonrpc","method"]},"examples":[{"name":"search_sales_reps","value":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_sales_reps","arguments":{}}}},{"name":"list_open_opportunities","value":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_open_opportunities","arguments":{}}}}]}}},"responses":{"200":{"description":"JSON-RPC result or error envelope.","content":{"application/json":{"schema":{"type":"object"}}}},"204":{"description":"Notification acknowledged (notifications/initialized)."},"429":{"description":"Rate limit exceeded (JSON-RPC error -32000)."}}}},"/api/gemini/assessment":{"post":{"operationId":"geminiAssessment","summary":"AI-assisted candidate assessment","description":"Server-side Gemini call; the API key never leaves the server. Rate limit: 30 requests/minute per IP. Body fields are validated server-side.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Assessment result.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/gemini/workforce-plan":{"post":{"operationId":"geminiWorkforcePlan","summary":"AI-assisted workforce plan","description":"Server-side Gemini call; rate limit: 20 requests/minute per IP. Body fields are validated server-side.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Workforce plan.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/ready":{"get":{"operationId":"ready","summary":"Readiness probe — dependency check (200 ready / 503 degraded)","responses":{"200":{"description":"Dependencies reachable.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Dependency degraded or unconfigured.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/health":{"get":{"operationId":"health","summary":"Liveness probe (minimal public fields)","responses":{"200":{"description":"Service is live.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/version.json":{"get":{"operationId":"version","summary":"Deployed version and build metadata","responses":{"200":{"description":"Version document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}