{"openapi":"3.1.0","info":{"title":"career-sift LinkedIn API","description":"\nReturn the full **education and experience** of a LinkedIn member, from a profile URL or from a name search\nwith strict filters (e.g. name `Keshav Singhal` + education `Delhi Technological University`).\nIf no candidate matches the filters nothing is returned but `{\"status\": \"profile_not_found\"}`.\n\n* **`GET /api/scrape`** — synchronous, answers in seconds to a minute.\n* **`POST /api/jobs`** — queue a search; a background worker runs jobs one at a time with a polite delay and\n  retries with exponential backoff when LinkedIn rate limits us.\n* **`POST /api/schedules`** — re-run a search every N hours to fill in data over time.\n* Every result is stored: **`GET /api/profiles`**.\n\nWrite endpoints (POST/DELETE) need header `x-api-key` when the server has `API_KEY` set. Errors are always\n`{\"error\": \"<friendly message>\"}`.\n","version":"1.0.0"},"paths":{"/api/scrape":{"get":{"tags":["scrape"],"summary":"Scrape a profile now","description":"Runs the scraper synchronously and stores the result (see `profile_id`).\n\nGive `url` for a direct profile, or `name` plus optional `education` / `company` / `location` filters.\nOnly a profile that actually matches every filter is returned.","operationId":"scrape_api_scrape_get","parameters":[{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"LinkedIn profile URL.","examples":["https://www.linkedin.com/in/keshav-singhal-0541b123b"],"title":"Url"},"description":"LinkedIn profile URL."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Full name to search for (if no url).","examples":["Keshav Singhal"],"title":"Name"},"description":"Full name to search for (if no url)."},{"name":"education","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required school (aliases understood).","examples":["Delhi Technological University"],"title":"Education"},"description":"Required school (aliases understood)."},{"name":"company","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required company.","examples":["Google"],"title":"Company"},"description":"Required company."},{"name":"location","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required location.","examples":["New Delhi"],"title":"Location"},"description":"Required location."}],"responses":{"200":{"description":"A profile (`status: ok`) or `{status: profile_not_found, reason}`.","content":{"application/json":{"schema":{},"examples":{"found":{"value":{"status":"ok","name":"Keshav Singhal","url":"https://www.linkedin.com/in/keshav-singhal-0541b123b","education":[{"school":"Delhi Technological University","degree":"B.Tech","start":"2016","end":"2020"}],"experience":[],"profile_id":1}},"not_found":{"value":{"status":"profile_not_found","reason":"No candidate matched the filters","profile_id":2}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"LinkedIn is rate limiting us; queue a job instead.","content":{"application/json":{"example":{"error":"LinkedIn is rate limiting us right now. Try again later or queue a job.","status":"rate_limited","retry_after":600}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/jobs":{"post":{"tags":["jobs"],"summary":"Queue a scrape","description":"Queues a search and returns immediately with the job (`status: queued`). Poll `GET /api/jobs/{id}`.\n\nThe worker runs one job at a time, waiting `MIN_DELAY_SECONDS` (default 20) between jobs; rate-limited\njobs are re-queued with exponential backoff (`next_run_at`).","operationId":"create_job_api_jobs_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required when the server sets API_KEY.","title":"X-Api-Key"},"description":"Required when the server sets API_KEY."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchParams"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get a job","description":"Status of a queued job; once `done`, `result` holds the profile or `profile_not_found`.","operationId":"get_job_api_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"integer","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles":{"get":{"tags":["profiles"],"summary":"List stored results","description":"Every stored result (from scrapes, jobs and schedules), newest first. Fetch one for the full data.","operationId":"list_profiles_api_profiles_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max items.","default":50,"title":"Limit"},"description":"Max items."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip (paging).","default":0,"title":"Offset"},"description":"Items to skip (paging)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProfileSummary"},"title":"Response List Profiles Api Profiles Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/{profile_id}":{"get":{"tags":["profiles"],"summary":"Get a stored result","description":"One stored result with the full normalized profile in `result`.","operationId":"get_profile_api_profiles__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"integer","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredProfile"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/schedules":{"post":{"tags":["schedules"],"summary":"Create a recurring search","description":"Re-runs the search every `every_hours` (or `interval`, e.g. `6h`, `@daily`). The first job is queued within a\nminute; results land in `GET /api/profiles`. A schedule never piles up jobs while one is still pending.","operationId":"create_schedule_api_schedules_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required when the server sets API_KEY.","title":"X-Api-Key"},"description":"Required when the server sets API_KEY."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["schedules"],"summary":"List schedules","description":"All recurring searches, newest first.","operationId":"list_schedules_api_schedules_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Schedule"},"title":"Response List Schedules Api Schedules Get"}}}}}}},"/api/schedules/{schedule_id}":{"delete":{"tags":["schedules"],"summary":"Delete a schedule","description":"Stops a recurring search and drops its still-queued jobs. Stored results are kept.","operationId":"delete_schedule_api_schedules__schedule_id__delete","parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"integer","title":"Schedule Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required when the server sets API_KEY.","title":"X-Api-Key"},"description":"Required when the server sets API_KEY."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"deleted":1}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/wrong x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Error":{"properties":{"error":{"type":"string","title":"Error","examples":["Job 42 not found."]}},"type":"object","required":["error"],"title":"Error"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Job":{"properties":{"id":{"type":"integer","title":"Id","examples":[1]},"status":{"type":"string","title":"Status","description":"queued | running | done | error","examples":["done"]},"params":{"additionalProperties":true,"type":"object","title":"Params","examples":[{"education":"Delhi Technological University","name":"Keshav Singhal"}]},"attempts":{"type":"integer","title":"Attempts","description":"How many times the worker has tried this job.","examples":[1]},"next_run_at":{"type":"number","title":"Next Run At","description":"Unix time the job becomes eligible to run (backoff after rate limits)."},"created_at":{"type":"number","title":"Created At"},"updated_at":{"type":"number","title":"Updated At"},"schedule_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Schedule Id","description":"Schedule that queued this job, if any."},"profile_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Profile Id","description":"Stored result id (see GET /api/profiles/{id})."},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"Scrape result: a profile (`status: ok`) or `{status: profile_not_found, reason}`; last rate-limit info while retrying."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","status","params","attempts","next_run_at","created_at","updated_at"],"title":"Job"},"ProfileSummary":{"properties":{"id":{"type":"integer","title":"Id","examples":[1]},"created_at":{"type":"number","title":"Created At"},"params":{"additionalProperties":true,"type":"object","title":"Params","description":"The search that produced this result."},"status":{"type":"string","title":"Status","description":"ok | profile_not_found","examples":["ok"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","examples":["Keshav Singhal"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","examples":["https://www.linkedin.com/in/keshav-singhal-0541b123b"]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline"}},"type":"object","required":["id","created_at","params","status"],"title":"ProfileSummary"},"Schedule":{"properties":{"id":{"type":"integer","title":"Id","examples":[1]},"params":{"additionalProperties":true,"type":"object","title":"Params","examples":[{"education":"Delhi Technological University","name":"Keshav Singhal"}]},"every_hours":{"type":"number","title":"Every Hours","examples":[24]},"created_at":{"type":"number","title":"Created At"},"last_run_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Last Run At","description":"Last time a job was queued for this schedule."},"next_run_at":{"type":"number","title":"Next Run At","description":"Unix time the next job will be queued."}},"type":"object","required":["id","params","every_hours","created_at","next_run_at"],"title":"Schedule"},"ScheduleIn":{"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"LinkedIn profile URL. If given, name search is skipped.","examples":["https://www.linkedin.com/in/keshav-singhal-0541b123b"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Person's full name to search for.","examples":["Keshav Singhal"]},"education":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Education","description":"School the person must have attended (aliases understood, e.g. DTU = Delhi College of Engineering).","examples":["Delhi Technological University"]},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company the person must have worked at.","examples":["Google"]},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Location the profile must mention.","examples":["New Delhi"]},"every_hours":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Every Hours","description":"Run the search every N hours (min 0.25).","examples":[24]},"interval":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interval","description":"Alternative to every_hours: `30m`, `6h`, `1d`, `2w`, `@hourly`, `@daily` or `@weekly`.","examples":["@daily"]}},"type":"object","title":"ScheduleIn","examples":[{"education":"Delhi Technological University","every_hours":24,"name":"Keshav Singhal"},{"interval":"@weekly","url":"https://www.linkedin.com/in/keshav-singhal-0541b123b"}]},"SearchParams":{"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"LinkedIn profile URL. If given, name search is skipped.","examples":["https://www.linkedin.com/in/keshav-singhal-0541b123b"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Person's full name to search for.","examples":["Keshav Singhal"]},"education":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Education","description":"School the person must have attended (aliases understood, e.g. DTU = Delhi College of Engineering).","examples":["Delhi Technological University"]},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company the person must have worked at.","examples":["Google"]},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Location the profile must mention.","examples":["New Delhi"]}},"type":"object","title":"SearchParams","examples":[{"education":"Delhi Technological University","name":"Keshav Singhal"},{"url":"https://www.linkedin.com/in/keshav-singhal-0541b123b"}]},"StoredProfile":{"properties":{"id":{"type":"integer","title":"Id","examples":[1]},"created_at":{"type":"number","title":"Created At"},"params":{"additionalProperties":true,"type":"object","title":"Params","description":"The search that produced this result."},"status":{"type":"string","title":"Status","description":"ok | profile_not_found","examples":["ok"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","examples":["Keshav Singhal"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","examples":["https://www.linkedin.com/in/keshav-singhal-0541b123b"]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline"},"result":{"additionalProperties":true,"type":"object","title":"Result","description":"Full normalized result: name, headline, location, url, education[], experience[], about, … or `{status: profile_not_found, reason}`."}},"type":"object","required":["id","created_at","params","status","result"],"title":"StoredProfile"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"scrape","description":"Synchronous scraping."},{"name":"jobs","description":"Queued scrapes processed in the background."},{"name":"profiles","description":"Stored results, newest first."},{"name":"schedules","description":"Recurring searches."}]}