{"openapi":"3.1.0","info":{"title":"Helix Human Capital API","version":"1.0.0","description":"Search and match a pool of consented candidates, parse resumes and job descriptions, and read market pay and open roles. Billing is by credits inside a fixed monthly plan. Credits per call: search 1, full record 5, CV link 2, parse 2, fit 3, match 10; market, jobs and account calls are free. Calls that fail on our side are refunded. Test keys (hlx_test_) return synthetic data only. Every response carries x-request-id and x-credits-charged. Send an `Idempotency-Key` header (8-200 characters) on any POST to make retries safe: the same key with the same body replays the stored response without charging again (kept 24 hours); the same key with a different body is rejected with 422."},"servers":[{"url":"https://api.helixhumancapital.in"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/plans":{"get":{"summary":"Public price list","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/me":{"get":{"summary":"This key: plan, scopes, credits left (free)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"summary":"Calls and credits per endpoint (free)","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"post":{"summary":"Ranked candidates for a natural-language query (1 credit; +5 per record when expand=true)","description":"Scope: search. With expand=true each result is a full record limited to the field scopes the key has; every release is logged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"expand":{"type":"boolean","default":false},"exclude":{"type":"array","items":{"type":"integer"},"description":"Candidate ids to skip (paging)."},"filters":{"type":"object","properties":{"seniority":{"type":"array","items":{"enum":["early","mid","senior","leadership"]}},"maxNoticeDays":{"type":"integer"},"city":{"type":"string"},"maxExpectedLpa":{"type":"number"},"minYears":{"type":"number"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/candidates/{id}":{"get":{"summary":"Full candidate record (5 credits)","description":"Scope: search. Contact, compensation and document fields appear only with the pii:contact, pii:comp and pii:docs scopes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"candidate":{"$ref":"#/components/schemas/Candidate"}}}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/candidates/{id}/cv":{"get":{"summary":"10-minute resume download link (2 credits)","description":"Scope: pii:docs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expiresInSeconds":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/match":{"post":{"summary":"Best-fitting candidates for a job description (10 credits; +5 per record when expand=true)","description":"Scope: match.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jobDescription"],"properties":{"jobDescription":{"type":"string","minLength":80,"maxLength":12000},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"expand":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Scoring temporarily unavailable. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fit":{"post":{"summary":"How well one candidate fits one job description (3 credits)","description":"Scope: match.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidateId","jobDescription"],"properties":{"candidateId":{"type":"integer"},"jobDescription":{"type":"string","minLength":80,"maxLength":12000}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/parse/resume":{"post":{"summary":"Resume file to structured JSON (2 credits)","description":"Scope: parse. PDF, DOC or DOCX up to 5 MB. Nothing is stored.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unreadable file. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/parse/jd":{"post":{"summary":"Job description to a requirement checklist (2 credits)","description":"Scope: parse.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jobDescription"],"properties":{"jobDescription":{"type":"string","minLength":80,"maxLength":12000}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/market/pay-bands":{"get":{"summary":"Market pay for a role (free)","description":"Scope: market. Curated benchmarks plus observed percentiles of self-reported fixed pay (INR lakh per annum) among the people nearest the role, overall and by seniority, with a confidence level. Groups smaller than 5 people are never shown.","parameters":[{"name":"role","in":"query","required":true,"schema":{"type":"string","minLength":3}},{"name":"city","in":"query","schema":{"type":"string"},"description":"Restrict observed pay to people currently in this city."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/market/skills":{"get":{"summary":"Most common skills near a role, or across the pool (free)","description":"Scope: market.","parameters":[{"name":"role","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/market/overview":{"get":{"summary":"Shape of the candidate pool (free)","description":"Scope: market. Seniority mix, top cities, notice periods, work mode. Cached for an hour.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"post":{"summary":"Register a webhook endpoint (free)","description":"https only. The signing secret is returned once. Each delivery carries `Helix-Signature: t=<unix>,v1=<hex>` where v1 is HMAC-SHA256 of `<t>.<raw body>` with the secret; reject signatures older than 5 minutes. Failed deliveries retry with backoff (30s, 2m, 10m, 1h, 6h, 24h). Events: credits.low, credits.exhausted, subscription.renewed, subscription.expiring, subscription.expired, webhook.test.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Defaults to all events."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid URL or events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Endpoint limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List webhook endpoints (free)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Remove a webhook endpoint (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/test":{"post":{"summary":"Send a signed test event now (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"summary":"Last 25 deliveries to an endpoint (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mcp":{"post":{"summary":"Model Context Protocol server (JSON-RPC 2.0 over HTTP)","description":"Stateless Streamable-HTTP MCP endpoint. Tools: search_candidates, get_candidate, get_candidate_cv, match_job_description, score_candidate_fit, parse_job_description, parse_resume, market_pay_bands, market_skills, market_overview, list_jobs, account_status. Each runs the same handler as its REST route, so scopes and credits are identical.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Notification accepted."},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs":{"get":{"summary":"Open roles (free)","description":"Scope: jobs.","parameters":[{"name":"team","in":"query","schema":{"type":"string"}},{"name":"level","in":"query","schema":{"enum":["junior","mid","senior","lead"]}},{"name":"mode","in":"query","schema":{"enum":["ON_SITE","HYBRID","REMOTE"]}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{slug}":{"get":{"summary":"One open role (free)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/checkout":{"post":{"summary":"Start a payment for a plan period or a top-up (INR, Cashfree)","description":"Also works on a key whose period has ended. Paying starts a fresh 30-day period; unused credits do not carry over.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","phone"],"properties":{"kind":{"enum":["plan","topup"]},"plan":{"enum":["pro","pro_scale"]},"packs":{"type":"integer","minimum":1,"maximum":20,"description":"Top-up packs of 1,000 credits."},"phone":{"type":"string","description":"10-digit mobile, required by the payment gateway."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"amountInr":{"type":"number"},"payUrl":{"type":"string"}}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/chat":{"post":{"summary":"Conversational search (anonymised), streamed. Scope: chat.","responses":{"200":{"description":"Server-sent event stream."},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/resumes":{"post":{"summary":"Contribute resumes to the pool (multipart). Scope: ingest.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feedback":{"post":{"summary":"Rate candidates returned by chat. Scope: feedback.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan period ended, or not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope, or is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for the plan exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"hlx_live_… or hlx_test_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"Me":{"type":"object"},"SearchResponse":{"type":"object","properties":{"query":{"type":"string"},"expanded":{"type":"boolean"},"count":{"type":"integer"},"appliedFilters":{"type":"object"},"filtersRelaxed":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}}}},"Candidate":{"type":"object","description":"contact, compensation and cv appear only when the key holds pii:contact, pii:comp and pii:docs respectively.","properties":{"id":{"type":"integer"},"role":{"type":["string","null"]},"seniority":{"type":["string","null"]},"yearsExperience":{"type":["number","null"]},"skills":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"fit":{"enum":["strong","possible","stretch",null]},"contact":{"type":"object","properties":{"name":{},"email":{},"phone":{},"linkedinUrl":{},"portfolioUrl":{},"currentCompany":{}}},"compensation":{"type":"object","description":"INR, lakh per annum. Self-reported by the candidate; not verified.","properties":{"currentFixedLpa":{},"currentVariableLpa":{},"expectedLpa":{},"noticeDays":{},"servingNotice":{},"employmentStatus":{}}},"cv":{"type":"object","properties":{"url":{"type":"string"}}}}}}}}