# Reed.co.uk API — UK jobs scraper: search Reed job postings by keyword, location, salary, distance, job-type, date and remote/hybrid filters; get full job detail (title, company, salary, location, description, contract type, sector, apply link); list all jobs at a company; and browse jobs by sector — from reed.co.uk, no login or API key required

> Search Reed.co.uk job postings by keyword with optional location, distance, salary range, job-type, date-posted, remote and sort filters. Returns up to 25 jobs per page with title, company, salary, location, dates and a plain-text description.
> ReefAPI engine `reed` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/reed/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /reed/v1/search — 1 credit
Search Reed.co.uk job postings by keyword with optional location, distance, salary range, job-type, date-posted, remote and sort filters. Returns up to 25 jobs per page with title, company, salary, location, dates and a plain-text description.

**Parameters:**
- `keywords` (string, required) — What job to search for — a job title, skill or keyword ('python developer', 'registered nurse', 'accountant').
- `location` (string, optional) — UK town, city or region to search in (free text, e.g. 'London', 'Manchester', 'Birmingham'). Pair with `distance`.
- `distance` (integer, optional, default 10) — Search radius in miles around the location (Reed bands: 0/1/3/5/10/15/20/30/50).
- `job_type` (enum, optional) — Restrict to one employment type. [one of: permanent, temporary, contract]
- `full_time` (boolean, optional) — Only full-time jobs.
- `part_time` (boolean, optional) — Only part-time jobs.
- `graduate` (boolean, optional) — Only graduate-level jobs.
- `agency` (boolean, optional) — Only jobs posted by recruitment agencies.
- `employer` (boolean, optional) — Only jobs posted directly by the employer (not an agency).
- `salary_from` (integer, optional) — Minimum annual salary in GBP (Reed banded, e.g. 40000).
- `salary_to` (integer, optional) — Maximum annual salary in GBP (Reed banded, e.g. 80000).
- `date_posted` (enum, optional) — Only jobs posted within this window. [one of: anytime, today, lastthreedays, lastweek, lasttwoweeks]
- `remote` (enum, optional) — Filter by working arrangement. [one of: remote, hybrid, onsite]
- `visa_sponsorship` (boolean, optional) — Only jobs offering visa sponsorship.
- `easy_apply` (boolean, optional) — Only Reed 'Easy Apply' jobs.
- `sort` (enum, optional, default "default") — Result ordering. [one of: default, date, salarydesc, salaryasc, distance]
- `page` (integer, optional, default 1) — Result page (25 jobs per page). Page until meta.total_pages.

**Returns:** jobs[]{job_id, title, url, company, company_slug, location, county, job_type, is_full_time, is_part_time, remote_option, posted_date, expiry_date, salary_from, salary_to, salary_description, currency, sector_top, sector, is_easy_apply, is_promoted, description_text} + total + meta.pagination{page, total_pages, has_more, next_page}

**Example request body:**
```json
{
  "keywords": "python developer",
  "location": "London"
}
```

### POST /reed/v1/detail — 1 credit
Full posting for one Reed job by job_id (or a Reed job URL): title, company, salary (range + display), location breakdown (town/county/region/country/postcode/remote), full HTML + plain-text description, contract type, sector, eligibility, dates and breadcrumbs — plus related jobs.

**Parameters:**
- `job_id` (string, optional) — Reed job ID — the number in the job URL (reed.co.uk/jobs/<slug>/<job_id>) or `job_id` from search.
- `url` (string, optional) — Alternatively a full Reed job URL.
- `include_similar` (boolean, optional, default false) — Also return Reed's related/similar jobs for this posting.

**Returns:** job{job_id, title, url, company, company_slug, company_profile_url, description_text, description_html, contract_type, is_full_time, is_part_time, is_agency, location, town, county, region, country, post_code, is_remote, salary_from, salary_to, salary_description, currency, sector, parent_sector, posted_date, expiry_date, breadcrumbs[]} + similar_jobs[] (with include_similar)

### POST /reed/v1/company-jobs — 1 credit
All public job postings at a specific company on Reed. Pass the company's Reed profile slug, full company URL, or its name; optionally narrow with the same keyword/location/salary/job-type/date filters as search.

**Parameters:**
- `company` (string, required) — The employer — its Reed company profile slug (the part of reed.co.uk/jobs/<slug>-jobs), a full Reed company URL, or the company name (resolved to a slug automatically). The `company_slug` field on any search result is a valid input.
- `keywords` (string, optional) — Optional: also filter the company's jobs by keyword.
- `location` (string, optional) — UK town, city or region to search in (free text, e.g. 'London', 'Manchester', 'Birmingham'). Pair with `distance`.
- `distance` (integer, optional, default 10) — Search radius in miles around the location (Reed bands: 0/1/3/5/10/15/20/30/50).
- `job_type` (enum, optional) — Restrict to one employment type. [one of: permanent, temporary, contract]
- `salary_from` (integer, optional) — Minimum annual salary in GBP (Reed banded, e.g. 40000).
- `salary_to` (integer, optional) — Maximum annual salary in GBP (Reed banded, e.g. 80000).
- `date_posted` (enum, optional) — Only jobs posted within this window. [one of: anytime, today, lastthreedays, lastweek, lasttwoweeks]
- `remote` (enum, optional) — Filter by working arrangement. [one of: remote, hybrid, onsite]
- `sort` (enum, optional, default "default") — Result ordering. [one of: default, date, salarydesc, salaryasc, distance]
- `page` (integer, optional, default 1) — Result page (25 jobs per page). Page until meta.total_pages.

**Returns:** jobs[]{job_id, title, url, company, company_slug, location, county, job_type, is_full_time, is_part_time, remote_option, posted_date, expiry_date, salary_from, salary_to, salary_description, currency, sector_top, sector, is_easy_apply, is_promoted, description_text} + total + meta.pagination{page, total_pages, has_more, next_page} + company

### POST /reed/v1/sector — 1 credit
Browse Reed jobs by sector/category (e.g. 'it', 'accountancy', 'healthcare', 'engineering', 'sales', 'marketing'). Optionally scope by location and the same salary/job-type/date/remote filters as search.

**Parameters:**
- `sector` (string, required) — Reed sector slug — e.g. 'it', 'accountancy', 'healthcare', 'engineering', 'sales', 'marketing', 'education', 'construction', 'hospitality', 'legal'.
- `location` (string, optional) — UK town, city or region to search in (free text, e.g. 'London', 'Manchester', 'Birmingham'). Pair with `distance`.
- `distance` (integer, optional, default 10) — Search radius in miles around the location (Reed bands: 0/1/3/5/10/15/20/30/50).
- `job_type` (enum, optional) — Restrict to one employment type. [one of: permanent, temporary, contract]
- `salary_from` (integer, optional) — Minimum annual salary in GBP (Reed banded, e.g. 40000).
- `salary_to` (integer, optional) — Maximum annual salary in GBP (Reed banded, e.g. 80000).
- `date_posted` (enum, optional) — Only jobs posted within this window. [one of: anytime, today, lastthreedays, lastweek, lasttwoweeks]
- `remote` (enum, optional) — Filter by working arrangement. [one of: remote, hybrid, onsite]
- `sort` (enum, optional, default "default") — Result ordering. [one of: default, date, salarydesc, salaryasc, distance]
- `page` (integer, optional, default 1) — Result page (25 jobs per page). Page until meta.total_pages.

**Returns:** jobs[]{job_id, title, url, company, company_slug, location, county, job_type, is_full_time, is_part_time, remote_option, posted_date, expiry_date, salary_from, salary_to, salary_description, currency, sector_top, sector, is_easy_apply, is_promoted, description_text} + total + meta.pagination{page, total_pages, has_more, next_page}

**Example request body:**
```json
{
  "sector": "it"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=reed
- Human docs page: https://reefapi.com/docs/reed
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt