Developers

The Search API

/api/search is the endpoint our own search page calls. It is public, it needs no authentication, and it is not rate limited. If you are building a job aggregator, a research project, or a browser extension that wants to know what the luxury houses are hiring for, this is the front door.

There is no database behind it. The entire catalogue lives in memory on regional servers in Singapore, Virginia, Oregon and Paris, and each request is answered by whichever is nearest. A typical query is served in a few milliseconds.

GET https://ceruleanjobs.com/api/search?query=atelier&location=paris

The machine-readable definition of everything below is published as an OpenAPI 3.1 document. Point your client generator at it rather than transcribing this page by hand.

A first request

With no parameters at all, you get the most recent listings — every parameter below is optional.

curl "https://ceruleanjobs.com/api/search?query=atelier&location=paris&limit=2"

Parameters

Every parameter is optional, including limit and offset. There is no required parameter and no minimum query — omitting a filter simply means no constraint on that field, and omitting limit returns 12 results.

Every example below is a live link — click it to see the JSON in your browser.

Searching

Filtering

All filters are exact matches against a lowercased index.

Paging

Omit limit and you get 12 results, the same page size the site’s own search uses; omit offset and you start at the first result.

Paging is native to the index, so a request at offset 9,000 costs no more than one at offset 0. A large limit is cheaper than several small ones — please prefer it.

Filter values

employment-type, seniority-level, industry and department each accept a fixed set of values. Anything outside these sets is not an error — it simply matches nothing. Every value below is a live link.

employment-type

seniority-level

industry

department

† Valid values that currently have no open listings, so they return total: 0.

brand and country are open-ended rather than fixed — browse all brands and all locations for the available slugs.

How values are encoded

Send filter values lowercased, using + or %20 for spaces.

✓ location=new+york
✗ location=New%20York

Values are trimmed and truncated to 200 characters.

Nothing returns an error

The endpoint always answers 200. A filter that matches nothing gives you total: 0, not a 404. A limit of banana falls back to 12. An offset of five million is clamped to 10,000. This is deliberate — a search that finds nothing is a valid answer to a valid question, and clients should not need error handling for a typo in a query string.

The response

{
  "results": [
    {
      "title": "Atelier Manager",
      "slug": "atelier-manager-chanel-paris",
      "url": "/jobs/atelier-manager-chanel-paris/",
      "description": "Lead the couture atelier, overseeing a team of premières and seamstresses through each collection.",
      "city": "Paris",
      "region": "Île-de-France",
      "country": "France",
      "datePosted": "2026-08-14T09:12:00Z",
      "paintingUrl": "/images/paintings/atelier-manager.webp",
      "brand": { "slug": "chanel", "name": "Chanel", "hasLogo": true },
      "employmentType": "Full-time",
      "seniorityLevel": "Senior",
      "industry": "Fashion",
      "department": "Production"
    }
  ],
  "total": 37,
  "hasMore": true,
  "limit": 2,
  "offset": 0
}

total is the number of listings matching your query across every page, not the length of results.

url is always the English /jobs/{slug}/ form, even when requested from cerulean.fr. Prepend https://ceruleanjobs.com for an absolute link.

description is a plain-text excerpt truncated to 300 characters, and is absent when a listing has none. Fields we could not classify come back as empty strings rather than being omitted.

Similar jobs

Pass a slug as similar and the ranking changes entirely. Instead of matching words, it ranks by meaning and geography — semantic similarity against a 512-dimension embedding, how close the location is, and how recent the listing is.

curl "https://ceruleanjobs.com/api/search?similar=atelier-manager-chanel-paris"

The subject job is excluded from its own results, so total needs no adjustment. Any brand filter is ignored, because the point is to cross between houses. If the slug is unknown, or too new to have an embedding, the request quietly falls back to an ordinary recency-ranked search rather than failing.

How results are ranked

An ordinary search blends three signals: text relevance, how recently the listing appeared weighted by the standing of the house, and how close the listing sits to your query in meaning. Similarity mode drops text relevance and leans on meaning and location instead.

The practical consequence is that recency matters. A perfect keyword match from three months ago will sit below a good match from this morning.

Freshness and caching

The index is rebuilt roughly every four hours, so results can trail the site by up to one cycle. Responses are cached at the edge for an hour. Both are worth knowing if you are diffing our data against your own.

Being a good citizen

Crawlers are welcome here — we have deliberately left the endpoint open. Two requests in return.

Send a User-Agent that identifies your project and gives us a way to reach you, so we can get in touch if something goes wrong at your end or ours. And ask for large pages rather than many small ones; limit=48 costs us no more than limit=1.

If you are building something substantial, we would genuinely like to hear about it. Write to us via the about page.