ceruleanjobs-com Search API

openapi: 3.2.0
info:
  title: Cerulean Search API
  version: 2.2.0
  summary: Public, unauthenticated search over the Cerulean luxury job board.
  description: '`GET /api/search` is the public search endpoint behind

    ceruleanjobs.com/search/. It is the same

    endpoint the site''s own search page calls, and it is open to anyone — there

    is no API key, no authentication, and no rate limit. If you are pointing an AI agent at Cerulean rather than writing a client by

    hand, `POST /api/mcp` is the same engine as a Model Context Protocol server. See **The MCP server** below. Requests are answered from an in-memory index held by regional Lambdas in

    Singapore, Virginia, Oregon and Paris. Route 53 latency routing sends each

    caller to the nearest one, and there is no database in the query path. Median server time is a few milliseconds. ### The MCP server


    `POST /api/mcp` is a Model Context Protocol

    server over the same index, `cerulean-jobs` version 3.0.0. It exists so a

    model can search the board without being handed this document and asked to

    write a client: three read-only tools — `search`, `fetch` and

    `find_similar_jobs` — carry their own JSON Schemas, including the complete

    list of valid values for the four taxonomy filters. It speaks protocol revision `2026-07-28`, which is stateless: there is no

    handshake to complete, no session ID to keep, and no connection to hold

    open, so one HTTP POST is one complete tool call. Clients on the earlier

    revisions, `2024-11-05` to `2025-11-25`, open with `initialize` as they

    always have and are answered request by request too. Point a client at

    `https://ceruleanjobs.com/api/mcp` and it works, with the same absence of

    keys and sign-up as the REST endpoint. The tools return shapes of their own, published as output schemas. `search`

    and `fetch` follow OpenAI''s search/fetch standard — results carry `id`,

    `title` and `url`, and `fetch` returns `{id, title, text, url, metadata}`,

    the whole listing — and beside those carry a listing''s brand, place, date

    and taxonomy slugs as `SearchResult` does. Their `warnings` use this

    document''s codes, plus `detail_unavailable` when `fetch` can serve only a

    listing''s summary, and `indexBuiltAt` means what it means here. Every link

    they return carries `utm_medium=mcp`. The one place they behave differently

    from this endpoint is invalid filter values: the REST endpoint answers with

    `200`, `total: 0` and an `unknown_enum_value` warning, while the tool schema

    rejects the value and names the ones that would have worked. That is a

    better answer for a model, which can correct itself and call again. ### What changed in 2.2.0 — 2026-09-24


    Additive only. `brand`, `location` and `country` take names as people write

    them as well as slugs, and a value that names nothing on file raises the new

    `unknown_value` warning, with close spellings in the new, optional

    `Warning.suggestions`. The MCP server moved to version 3.0.0: its tools are

    now `search`, `fetch` and `find_similar_jobs`, described under `/api/mcp`,

    and `GET` and `DELETE` on that path answer `405`. `X-Cerulean-Api-Version`

    still reads `2`. ### What changed in 2.1.0 — 2026-08-21


    Additive only; nothing in the `GET /api/search` contract changed. The MCP

    server described above was added at `POST /api/mcp`, and this document gained

    the `/api/mcp` path below. `X-Cerulean-Api-Version` still reads `2`. ### What changed in 2.0.0 — 2026-08-20


    Two breaking changes, both in the response body. A client that reads `url`

    or `brand.hasLogo` must be updated; every example below shows the new form. * **`url` is now an absolute URL** — `https://ceruleanjobs.com/jobs/{slug}/`

    rather than the bare path `/jobs/{slug}/`. Nothing has to be prepended any

    more. `slug` is unchanged and is still the stable identifier to pass back

    to `similar` and to the new `slug` parameter. * **`brand.hasLogo` is replaced by `brand.logoUrl`** — emitted only when a

    logo exists, so its presence carries the same signal the boolean did, and

    the URL comes with it.'
  contact:
    name: Cerulean
    url: https://ceruleanjobs.com/about/
  license:
    name: Job data may be used for personal, editorial and commercial purposes, crediting Cerulean and linking each listing to its url.
    url: https://ceruleanjobs.com/about/developers/#terms-and-attribution
servers:
- url: https://ceruleanjobs.com
  description: Primary site (English) — `site=en`
- url: https://cerulean.fr
  description: France — `site=fr-fr`
- url: https://ceruleanjobs.ch
  description: Switzerland — `site=fr-ch`, and `site=de-ch` under /de/
- url: https://ceruleanjobs.ca
  description: Canada — `site=en-ca`, and `site=fr-ca` under /fr/
- url: https://ceruleanjobs.de
  description: Germany — `site=de-de`
- url: https://ceruleanjobs.co.uk
  description: United Kingdom — `site=en-gb`
- url: https://cerulean.es
  description: Spain — `site=es-es`
- url: https://ceruleanjobs.it
  description: Italy — `site=it-it`
- url: https://ceruleancareers.com
  description: United States — `site=en-us`
security: []
tags:


# --- truncated at 32 KB (39 KB total) ---
# Full source: https://artifacts.apis.io/ceruleanjobs-com/openapi/ceruleanjobs-com-search-api-openapi.yml