Developer API

v2 — Modern (recommended)

The richer, paginated, filterable REST endpoint. Use this for anything new. Structured location data, separate skills, stack, tools, schedule_type enum, ISO 8601 timestamps, and a trimmed company object. Salary values are in cents (e.g. 8000000 = $80,000 USD).

Endpoints

• GET /api/v2/jobs
• GET /api/v2/jobs/{slug}

Query parameters

Example request

curl 'https://4dayweek.io/api/v2/jobs?schedule=4_day_week&limit=5'

Example response

Wrapped in {data, page, limit, total, has_more}. One item from data shown below.

{
  "id": "018f...-uuid",
  "slug": "site-reliability-engineer-ggfft",
  "title": "Site Reliability Engineer",
  "description": "We are looking for an SRE to join the Cloud team...",
  "url": "https://4dayweek.io/job/site-reliability-engineer-ggfft",
  "category": "engineering",
  "role": "Site Reliability Engineer",
  "level": "mid",
  "contract_type": "permanent",
  "schedule_type": "4_day_week",
  "hours_per_week_min": 32,
  "hours_per_week_max": 32,
  "work_arrangement": "remote",
  "locations": [
    {"country": "Saudi Arabia", "continent": "Asia", "work_arrangement": "remote", "is_primary": true}
  ],
  "timezones": ["Asia/Riyadh"],
  "salary_min": 8000000,
  "salary_max": 12000000,
  "salary_currency": "USD",
  "salary_period": "year",
  "skills": [{"name": "Leadership", "slug": "leadership"}],
  "stack": [{"name": "Python", "slug": "python"}, {"name": "Kubernetes", "slug": "kubernetes"}],
  "tools": [{"name": "Datadog", "slug": "datadog"}],
  "posted_at": "2025-01-12T00:00:00Z",
  "expires_at": "2025-05-12T00:00:00Z",
  "company": {
    "id": "018f...-uuid",
    "slug": "lucidya",
    "name": "Lucidya",
    "url": "https://4dayweek.io/company/lucidya",
    "website": "https://lucidya.com",
    "logo_url": "https://media.4dayweek.io/companies/lucidya.png",
    "short_description": "Arabic NLP SaaS",
    "country": "Saudi Arabia",
    "employees": 100,
    "schedule_type": "4_day_week",
    "hours_full_time": 32,
    "work_life_score": 85
  }
}

Single job detail

curl 'https://4dayweek.io/api/v2/jobs/site-reliability-engineer-ggfft'

Returns a single V2JobDTO (same shape as an item from the list) or 404 if the slug is unknown.

v1 — Legacy

A compatibility lane that mirrors the field shape of the original 4dayweek.io/api endpoint. Kept so existing integrations keep working. Prefer v2 for new projects — v1 only supports page and limit, and its field names are legacy.

Endpoint

• GET /api/v1

Differences from the old /api

• Paginated now. The old endpoint dumped every live job in one blob; v1 defaults to 25 per page, max 100. Iterate ?page=1..N until has_more == false.
• id_str and company_id are UUID strings now (were integers in the old API).
• filters combines skills, tech stack, and tools into a single {label, value} list, deduped, matching the old shape.
• category, level, reduced_hours, and remote_level return human-readable labels matching the old API format.
• description_html is intentionally not exposed in either version — use the plain description field and render it yourself.
• total_raised is no longer included in company objects.

Example request

curl 'https://4dayweek.io/api/v1?page=1&limit=25'

Example response

Wrapped in {usage, page, total, has_more, jobs}. One item from jobs shown below.

{
  "id_str": "018f...-uuid",
  "title": "Site Reliability Engineer",
  "slug": "site-reliability-engineer-ggfft",
  "url": "https://4dayweek.io/job/site-reliability-engineer-ggfft",
  "description": "We are looking for an SRE...",
  "category": "Engineering",
  "role": "Site Reliability Engineer",
  "level": "Mid-level",
  "hours": 32,
  "reduced_hours": "Offered",
  "is_remote": true,
  "location_city": "Riyadh",
  "location_country": "Saudi Arabia",
  "location_continent": "Asia",
  "location_original": "Remote in Riyadh (Saudi Arabia)",
  "posted": 1736640000,
  "filters": [
    {"label": "Python", "value": "python"},
    {"label": "Kubernetes", "value": "kubernetes"}
  ],
  "company_id": "018f...-uuid",
  "company_name": "Lucidya",
  "company": {
    "id_str": "018f...-uuid",
    "name": "Lucidya",
    "slug": "lucidya",
    "url": "https://4dayweek.io/company/lucidya",
    "category": "Technology",
    "short_description": "Arabic NLP SaaS",
    "description": "...",
    "country": "Saudi Arabia",
    "employees": 100,
    "logo_url": "https://media.4dayweek.io/companies/lucidya.png",
    "company_url": "https://lucidya.com",
    "reduced_hours": "4 day week @ 100% salary",
    "four_day_reference_text": "We offer a 4-day work week at full pay.",
    "images": [],
    "remote_level": "100% remote"
  }
}

OpenAPI spec

A machine-readable OpenAPI 3.1 spec is served at /openapi.yaml. Import it into Postman, Insomnia, or a codegen tool to generate a typed client in your language of choice.

MCP server (for AI agents)

A read-only Model Context Protocol endpoint is served at /api/mcp over the streamable-HTTP transport. Point Claude, ChatGPT, Cursor, or any MCP-capable assistant at it and it can search reduced-hours jobs and employers directly, without scraping. No API key, no auth.

claude mcp add --transport http 4dayweek https://4dayweek.io/api/mcp

6 tools, all read-only:

• search_jobs — Live listings, filtered by schedule type, category, country, work arrangement, seniority, skills, work-life score or posting date.
• get_job — One listing in full by slug, including hours, locations and a published salary.
• search_companies — Employers by working-hours policy, country, office-presence policy and whether they hire worldwide.
• get_company — One employer's full profile: schedule policy, weekly hours, office policy, benefits and work-life score — plus day off, vacation and awards where the employer has published them.
• get_market_stats — Aggregate market data across tracked employers, carrying an as-of date and its own caveats.
• explain_schedule_type — Precise definitions: whether a schedule genuinely reduces weekly hours, and whether that is at full pay.

Search tools return at most 25 results per call and accept a page argument up to 200; each response carries has_more. The endpoint has its own rate limit of 300 requests per minute per IP sustained (bursting to 60), separate from the REST bucket above.

The tool descriptions carry the schedule taxonomy, so an assistant using them will not report a compressed 4x10 as a 4-day week — it is four days at the same 40 hours. Definitions are on our methodology page.

Full MCP documentation, with setup for every client →