Machine-readable API for AI agents and LLM tools.

{ "method": "POST", "path": "/v2/catalog/search", "auth": "Bearer htc_...", "content_type": "application/json", "request_schema": { "type": "object", "required": ["query_text"], "properties": { "query_text": { "type": "string", "description": "Natural-language hiring brief" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "rerank": { "type": "boolean", "default": false, "description": "Enable LLM reranking" }, "prompt_profile_id": { "type": "integer", "description": "Stored prompt profile ID" }, "years_experience_min": { "type": "number" }, "years_experience_max": { "type": "number" }, "current_ctc_inr_lpa_min": { "type": "number" }, "current_ctc_inr_lpa_max": { "type": "number" }, "preferred_locations": { "type": "array", "items": { "type": "string" } }, "referred_by": { "type": "array", "items": { "type": "string" } } } }, "response_schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#CatalogItem" } }, "query": { "type": "string" }, "source": { "type": "string", "enum": ["pinecone+mysql", "fallback_sql"] }, "reranked": { "type": "boolean" }, "routed_provider": { "type": "string" }, "prompt_profile_id": { "type": "integer" }, "request_id": { "type": "string" } } } }

{ "method": "GET", "path": "/v2/catalog/resumes/{resumeId}/detail", "params": { "resumeId": { "in": "path", "type": "integer", "required": true } }, "response_schema": { "type": "object", "properties": { "item": { "$ref": "#CatalogItem" }, "full_resume_text": { "type": "string", "description": "Anonymized or full text based on ownership" }, "request_id": { "type": "string" } } } }

{ "method": "GET", "path": "/v2/catalog/resumes/{resumeId}/similar", "params": { "resumeId": { "in": "path", "type": "integer", "required": true }, "limit": { "in": "query", "type": "integer", "default": 20 } }, "response": { "items": "CatalogItem[]", "request_id": "string" } }

{ "method": "POST", "path": "/v2/resumes/upload", "content_type": "multipart/form-data", "fields": { "resume": { "type": "file", "required": true, "accept": "application/pdf", "max_bytes": 15728640 }, "uploader_email": { "type": "string", "required": true }, "referrer_email": { "type": "string", "required": false }, "current_ctc": { "type": "string", "required": true }, "expected_ctc": { "type": "string", "required": true }, "preferred_location": { "type": "string", "required": true }, "years_of_experience": { "type": "string", "required": true }, "custom_notes": { "type": "string", "required": false }, "custom_data_json": { "type": "string", "required": false, "format": "json-object" } }, "response": { "accepted": "boolean", "is_resume": "boolean", "refer_id": "string", "alias_email": "string", "uploader_email": "string", "filename": "string", "resume_id": "integer", "credit_price": "integer", "credits_added": "integer", "request_id": "string" } }

{ "method": "POST", "path": "/v2/public/resumes/upload", "content_type": "multipart/form-data", "behavior": "Open website intake. Same field contract as /v2/resumes/upload, but no org ownership or credits are inferred from the browser request alone.", "response": { "accepted": "boolean", "is_resume": "boolean", "refer_id": "string", "uploader_email": "string", "filename": "string", "source": "public_website", "request_id": "string" } }

{ "method": "POST", "path": "/v2/shortlists", "request": { "resume_id": "integer (required)", "notes": "string (optional)" }, "response": { "message": "shortlisted", "request_id": "string" } } GET /v2/shortlists → { "items": [...], "request_id": "string" } DELETE /v2/shortlists/{resumeId} → { "message": "removed", "request_id": "string" }

{ "method": "POST", "path": "/v2/resumes/{resumeId}/claim", "request": { "recipient_emails": "string[] (optional)" }, "response": { "message": "string", "request_id": "string" } }

GET /v2/wallet/balance → { "balance_credits": integer } GET /v2/owned/resumes?limit=N&offset=N → { "items": OwnedResume[] } GET /v2/owned/resumes/{id}/detail → { "item": OwnedResume, "full_resume_text": string } GET /v2/resumes/{id}/metrics → { "resume_id": int, "shortlist_count": int, "fetch_count": int, "claim_count": int } POST /v2/api-keys { "name": string } → { "id": int, "raw_key": "htc_..." } GET /v2/api-keys → { "items": APIKey[] } DELETE /v2/api-keys/{id} → { "message": "revoked" } GET /v2/mail-aliases → { "items": Alias[], "alias_domain": string, "max_aliases": int } POST /v2/mail-aliases { "localpart": string, "forward_to_email"?: string, "forwarding_enabled"?: bool } PATCH /v2/mail-aliases/{id} → update forwarding DELETE /v2/mail-aliases/{id} GET /v2/mail-aliases/availability?localpart=X → { "available": bool } GET /v2/mail-forwarding/default → { "item": MailForwardingDefault, "default_source_email": string, "is_using_default_email": bool } PUT /v2/mail-forwarding/default { "forward_to_email": string, "forwarding_enabled": bool } GET /v2/inbox/messages?limit=N&offset=N → { "items": InboxMessage[] } GET /v2/inbox/messages/{id} → InboxMessage with attachments POST /v2/inbox/messages/{id}/reply { "body_text": string, "subject"?: string } POST /v2/inbox/messages/{id}/forward { "to_email": string, "note"?: string } POST /v2/byok/keys { "provider": "groq"|"cerebras"|"openrouter", "api_key": string } GET /v2/byok/keys → { "items": BYOKKey[] } DELETE /v2/byok/keys/{provider} POST /v2/search/prompt-profiles { "name": string, "prompt_text": string, "is_default"?: bool } GET /v2/search/prompt-profiles → { "items": PromptProfile[] } PATCH /v2/search/prompt-profiles/{id} { "prompt_text"?: string, "name"?: string } DELETE /v2/search/prompt-profiles/{id} GET /v2/org/members → { "items": Member[] } POST /v2/org/member-invites { "email": string, "role"?: string } GET /v2/portfolio/context → portfolio info POST /v2/portfolio/bootstrap { "name": string, "site_name"?: string, "site_tagline"?: string } GET /v2/portfolio/admin/settings → settings PATCH /v2/portfolio/admin/settings { "default_visibility_mode"?: string, ... } GET /v2/portfolio/admin/organizations → org list POST /v2/portfolio/admin/organizations { "org_id": string } GET /v2/resumes/{id}/visibility → { "visibility_mode": string } PATCH /v2/resumes/{id}/visibility { "visibility_mode": "private"|"portfolio_masked"|"portfolio_full" } GET /v2/auth/session/verify → { "user_id", "org_id", "email", "alias_email", "auth_method", "actor_type", "role" }

{ "resume_id": "integer", "external_resume_id": "string", "pinecone_id": "string", "title": "string", "summary": "string (anonymized, or full if purchased)", "profile_summary_50w": "string", "years_of_experience": "number", "jobs_worked_count": "integer", "max_job_duration_months": "integer", "current_ctc_inr_lpa": "number", "expected_ctc_inr_lpa": "number", "preferred_job_location": "string", "company_names": "string", "primary_company_name": "string", "uploaded_by": "string", "referred_by": "string", "price_credits": "integer", "purchased": "boolean", "score": "float (0-1 similarity score)", "match_explanation": "string (when reranked)", "match_score_100": "integer (0-100, when reranked)", "shortlist_count": "integer", "fetch_count": "integer", "claim_count": "integer", "tags": "string[]", "pdf_url": "string (presigned S3 URL)", "status": "string" }

{ "openapi": "3.1.0", "info": { "title": "Hidden Talent Club", "version": "2.0.0" }, "servers": [{ "url": "https://yourdomain.hiddentalent.club" }], "paths": { "/v2/catalog/search": { "post": { "operationId": "searchResumes", "summary": "Search resumes with semantic query and filters", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query_text"], "properties": { "query_text": { "type": "string" }, "limit": { "type": "integer", "default": 20 }, "rerank": { "type": "boolean" }, "years_experience_min": { "type": "number" }, "years_experience_max": { "type": "number" }, "current_ctc_inr_lpa_min": { "type": "number" }, "current_ctc_inr_lpa_max": { "type": "number" }, "preferred_locations": { "type": "array", "items": { "type": "string" } } } }}}} } }, "/v2/catalog/resumes/{resumeId}/detail": { "get": { "operationId": "getResumeDetail", "parameters": [{ "name": "resumeId", "in": "path", "required": true, "schema": { "type": "integer" } }] } }, "/v2/catalog/resumes/{resumeId}/similar": { "get": { "operationId": "getSimilarResumes", "parameters": [ { "name": "resumeId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ] } }, "/v2/shortlists": { "post": { "operationId": "addShortlist", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" }, "notes": { "type": "string" } } }}}} }, "get": { "operationId": "listShortlist" } }, "/v2/wallet/balance": { "get": { "operationId": "getBalance" } }, "/v2/resumes/{resumeId}/claim": { "post": { "operationId": "claimResume", "parameters": [{ "name": "resumeId", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_emails": { "type": "array", "items": { "type": "string" } } } }}}} } }, "/v2/owned/resumes": { "get": { "operationId": "listOwnedResumes" } }, "/v2/owned/resumes/{resumeId}/detail": { "get": { "operationId": "getOwnedResumeDetail", "parameters": [{ "name": "resumeId", "in": "path", "required": true, "schema": { "type": "integer" } }] } }, "/v2/inbox/messages": { "get": { "operationId": "listInboxMessages" } }, "/v2/inbox/messages/{id}/reply": { "post": { "operationId": "replyToMessage", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["body_text"], "properties": { "body_text": { "type": "string" }, "subject": { "type": "string" } } }}}} } }, "/v2/resumes/upload": { "post": { "operationId": "uploadResume", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["resume", "uploader_email", "current_ctc", "expected_ctc", "preferred_location", "years_of_experience"], "properties": { "resume": { "type": "string", "format": "binary" }, "uploader_email": { "type": "string", "format": "email" }, "referrer_email": { "type": "string", "format": "email" }, "current_ctc": { "type": "string" }, "expected_ctc": { "type": "string" }, "preferred_location": { "type": "string" }, "years_of_experience": { "type": "string" }, "custom_notes": { "type": "string" }, "custom_data_json": { "type": "string" } } }}}}} } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } } }, "security": [{ "bearer": [] }] }

[ { "name": "search_resumes", "description": "Search Hidden Talent Club resume catalog using natural language. Returns anonymized candidates with match scores.", "input_schema": { "type": "object", "required": ["query_text"], "properties": { "query_text": { "type": "string", "description": "Hiring brief" }, "limit": { "type": "integer", "default": 20, "description": "Max results 1-100" }, "rerank": { "type": "boolean", "default": false }, "years_experience_min": { "type": "number" }, "years_experience_max": { "type": "number" }, "current_ctc_inr_lpa_min": { "type": "number" }, "current_ctc_inr_lpa_max": { "type": "number" }, "preferred_locations": { "type": "array", "items": { "type": "string" } } }} }, { "name": "get_resume_detail", "description": "Get full anonymized detail of a resume by ID, including summary, experience, and pricing.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" } }} }, { "name": "find_similar_resumes", "description": "Find resumes similar to a given resume ID.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" }, "limit": { "type": "integer", "default": 10 } }} }, { "name": "add_to_shortlist", "description": "Add a resume to the recruiter's shortlist.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" }, "notes": { "type": "string" } }} }, { "name": "list_shortlist", "description": "List all shortlisted resumes.", "input_schema": { "type": "object", "properties": {} } }, { "name": "check_wallet_balance", "description": "Check current credit balance.", "input_schema": { "type": "object", "properties": {} } }, { "name": "purchase_resume", "description": "Purchase/claim a resume to unlock the full CV. Deducts credits.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" }, "recipient_emails": { "type": "array", "items": { "type": "string" } } }} }, { "name": "list_owned_resumes", "description": "List purchased/owned resumes.", "input_schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } }} }, { "name": "get_owned_resume_detail", "description": "Get full detail of a purchased resume.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" } }} }, { "name": "get_resume_metrics", "description": "Get shortlist/fetch/claim counters for a resume.", "input_schema": { "type": "object", "required": ["resume_id"], "properties": { "resume_id": { "type": "integer" } }} }, { "name": "list_inbox_messages", "description": "List inbox messages across all aliases.", "input_schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } }} }, { "name": "reply_to_message", "description": "Reply to an inbox message.", "input_schema": { "type": "object", "required": ["message_id", "body_text"], "properties": { "message_id": { "type": "integer" }, "body_text": { "type": "string" }, "subject": { "type": "string" } }} }, { "name": "upload_resume", "description": "Upload a PDF resume for processing and indexing.", "input_schema": { "type": "object", "required": ["file_path"], "properties": { "file_path": { "type": "string" }, "subject": { "type": "string" }, "notes": { "type": "string" } }} } ]

MCP URL: https://yourdomain.hiddentalent.club/mcp OAuth discovery: https://yourdomain.hiddentalent.club/.well-known/oauth-authorization-server Claude Desktop config (claude_desktop_config.json): { "mcpServers": { "hiddentalentclub": { "url": "https://yourdomain.hiddentalent.club/mcp", "headers": { "Authorization": "Bearer htc_YOUR_KEY" } } } } Available MCP tools (auto-discovered): resumes_search_v2 → Search with semantic query and filters resume_detail_get → Get anonymized resume detail owned_resume_detail_get → Get purchased resume detail resumes_similar → Find similar resumes resume_claim → Purchase a resume (requires idempotency_key) owned_resumes_list → List purchased resumes resume_metrics_get → Get engagement metrics recruiter_resumes_list → List org resumes with tags resume_tags_set → Set recruiter tags shortlist_add → Add to shortlist (requires idempotency_key) shortlist_list → List shortlist shortlist_remove → Remove from shortlist cart_add → Add to cart cart_list → List cart items cart_remove → Remove from cart wallet_balance → Check credits Scopes required per tool: resumes.read → search, detail, similar, metrics, owned list purchase.write → claim, cart, checkout shortlist → add, list, remove tags.write → resume_tags_set