Plucker API

Overview

The Plucker API turns a brief, written in plain English, into a ranked, scored shortlist sourced from LinkedIn. You POST a brief, get a run_id, poll it, and read the candidates when it is done.

Everything is a straight REST call. No SDK required. Any HTTP client works.

Authentication

Every call needs an X-API-Key header. Create keys under Settings → API keys. A key is shown once, at creation, so copy it then. Keys belong to your organisation, so they only ever see your organisation's searches. Rotate at any time by creating a new key and revoking the old one.

# every request carries the key
curl https://plucker-production.up.railway.app/api/scrape/{run_id} \
  -H "X-API-Key: plk_your_key_here"

Quickstart

Three requests to go from a brief to a shortlist. Keep the run_id from step 1 and poll step 2 until status is completed.

1. Start a search

curl -X POST https://plucker-production.up.railway.app/api/scrape \
  -H "X-API-Key: plk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Senior Python engineers at UK SaaS scale-ups, 5+ years, ideally with AWS and Postgres.",
    "target_quality": 20,
    "min_characteristics": "Must have Python + AWS. No agencies."
  }'

{
  "run_id": "8f4b1e2c-9d7a-4f6e-b3e2-1a9f8c5d3e7b",
  "status": "queued"
}

2. Poll until it completes

curl https://plucker-production.up.railway.app/api/scrape/8f4b1e2c-9d7a-4f6e-b3e2-1a9f8c5d3e7b \
  -H "X-API-Key: plk_your_key_here"

Every 5 to 10 seconds is fine. Runs typically take 30 to 60 minutes to complete, depending on target_quality. When status flips from running to completed you can read the shortlist.

3. Read the shortlist

curl https://plucker-production.up.railway.app/api/scrape/8f4b1e2c-9d7a-4f6e-b3e2-1a9f8c5d3e7b/candidates \
  -H "X-API-Key: plk_your_key_here"

Candidates come back ranked by score, highest first. Each has a LinkedIn URL, any contact details found so far, and Plucker's summary of why they matched.

POST/api/scrape

Starts a search. Returns straight away; the search runs in the background. Up to three searches run at once across the service. Anything beyond that waits in a queue and starts when a slot frees up, rather than failing.

Every brief is tidied by Format for me before the search starts, the same as on the New project screen: it is rewritten into the shape Plucker searches best, the likely employers are researched on the web, and the must-haves and places are pulled out. That takes up to a minute, and the run shows current_activity "Formatting the brief" meanwhile. Anything you send yourself (min_characteristics, target_companies, locations, name) is kept as you sent it; the formatter only fills what you left out. GET /api/scrape/{run_id} returns the formatted brief and what the search used.

Request body

Response · 200 OK

Errors

GET/api/scrape/{run_id}

The run's live status and progress. Poll it every 5 to 10 seconds while the run is in flight.

Response · 200 OK

Returns a Run object. The fields to watch:

Errors

GET/api/scrape/{run_id}/candidates

Every candidate stored on this run so far, ranked by score, highest first. By default nothing is filtered out: you get every stored candidate, whatever their score. Safe to call before the run finishes; the list grows as more candidates come in.

Query parameters

Response · 200 OK

GET/api/scrape/{run_id}/candidates/export/csv

The shortlist as CSV, ready to import into your ATS or a spreadsheet. The same data as the JSON candidates endpoint, with the fields flattened.

Response · 200 OK

Content-Type: text/csv. The header row includes score, full_name, linkedin_url, headline, current_title, current_company, current_company_domain, location, work_email, work_email_quality, personal_email, personal_email_quality, phone_number, rf_role, rf_market, rf_specialism, rf_geographies, rf_contract_or_perm, wave and summary.

curl https://plucker-production.up.railway.app/api/scrape/{run_id}/candidates/export/csv \
  -H "X-API-Key: plk_your_key_here" \
  -o shortlist.csv

Share links

A share link is a public, read-only page for one run's shortlist. Anyone with the URL can view it without signing in. Three endpoints manage it.

POST/api/scrape/{run_id}/share

Turns sharing on. Repeating it is safe: if a link already exists you get the same one back.

curl -X POST https://plucker-production.up.railway.app/api/scrape/{run_id}/share \
  -H "X-API-Key: plk_your_key_here"

{
  "share_token": "…",
  "share_url": "https://plucker.blootai.com/share/…"
}

POST/api/scrape/{run_id}/share/rotate

Issues a new link and stops the old one working. Use it when a link may have been forwarded further than intended. Same response as above.

curl -X POST https://plucker-production.up.railway.app/api/scrape/{run_id}/share/rotate \
  -H "X-API-Key: plk_your_key_here"

DEL/api/scrape/{run_id}/share

Turns sharing off. The public URL returns 404 from the next request.

curl -X DELETE https://plucker-production.up.railway.app/api/scrape/{run_id}/share \
  -H "X-API-Key: plk_your_key_here"

{ "ok": true }

Errors

Run object

Returned by POST /api/scrape (partly) and GET /api/scrape/{run_id} (in full).

{
  "run_id": "8f4b1e2c-9d7a-4f6e-b3e2-1a9f8c5d3e7b",
  "name": "Senior Python Engineers - UK SaaS",
  "status": "running",
  "brief": "Senior Python engineers at UK SaaS scale-ups...",
  "min_characteristics": "Must have Python + AWS.",
  "target_quality": 20,
  "quality_count": 12,
  "candidates_seen": 47,
  "wave": 2,
  "current_activity": "Scoring candidate from Monzo",
  "error": null,
  "started_at": "2026-07-12T14:24:11.827Z",
  "completed_at": null,
  "created_at": "2026-07-12T14:24:09.530Z"
}

Candidate object

Returned in the candidates array. A null field means Plucker did not find that detail: either it was not on LinkedIn, or nobody has looked it up yet.

{
  "id": "c8a7f2e0-4b3d-4e2a-a1c5-9f8b7d3e4a5c",
  "linkedin_url": "https://www.linkedin.com/in/sarah-chen-99182/",
  "full_name": "Sarah Chen",
  "headline": "Staff Engineer at Monzo · Python · Distributed systems",
  "current_title": "Staff Engineer",
  "current_company": "Monzo",
  "location": "London, United Kingdom",
  "profile_picture_url": "https://media.licdn.com/...",
  "score": 9,
  "summary": "8 years' Python experience across two Series-C fintechs. Deep AWS knowledge from the Monzo migration.",
  "wave": 1,
  "work_email": "sarah.chen@monzo.com",
  "work_email_quality": "verified",
  "personal_email": null,
  "personal_email_quality": null,
  "phone_number": null,
  "rf_role": "Backend engineer",
  "rf_market": "Fintech",
  "rf_specialism": "Distributed systems",
  "rf_geographies": "United Kingdom",
  "rf_contract_or_perm": "Permanent",
  "confidence_scores": { "role_fit": 0.94, "seniority": 0.98 },
  "created_at": "2026-07-12T14:26:33.117Z"
}

Field notes

Errors

Every error comes back as JSON with a detail string.

{ "detail": "Missing X-API-Key header" }

Status codes

Rate limits

Plucker rate-limits per API key, not per organisation.

Hit a 429? The Retry-After response header tells you the wait in seconds, and simple exponential backoff works. There are no quotas on candidates or contact lookups.

Changelog