French Joke of the Day API
Free JSON API, no key, HTTPS, CORS enabled. It returns one French joke per day: a setup (amorce), a punchline (chute) and a link to a page that explains why it is funny. The jokes are in French, and everyone normally gets the same one on a given UTC day. Every joke in the rotation was picked by hand and is suitable for all audiences.
Endpoint
Send a GET request to the endpoint below, over HTTPS. There is no key, no sign-up and no parameters.
GET https://deviens-marrant.fr/api/widget/v1/vanne-du-jourcurl -i https://deviens-marrant.fr/api/widget/v1/vanne-du-jourThe endpoint responds to GET (JSON) and OPTIONS (CORS preflight, 204 with no body). From the browser, send a plain GET: the preflight allows no request headers, so adding one such as Authorization, X-Requested-With or Content-Type: application/json makes the request fail with a CORS error. Server-side calls are not affected.
// <div id="joke" lang="fr"></div> then, in a <script type="module">:
try {
const res = await fetch("https://deviens-marrant.fr/api/widget/v1/vanne-du-jour");
if (res.ok) {
const joke = await res.json();
const link = document.createElement("a");
link.href = joke.attribution.url;
link.textContent = joke.attribution.name;
document.getElementById("joke").append(joke.amorce, " ", joke.chute, " ", link);
}
} catch {
// Network error or rate limit (the 429 has no CORS header): show nothing.
}Example response
A real response, returned on 24 October 2026 (indented here for reading; the API returns it on one line):
{
"type": "vanne",
"date": "2026-10-24",
"amorce": "Mon père m’envoie ses messages en MAJUSCULES.",
"chute": "Je réponds en minuscules. Il m’a demandé pourquoi je boudais.",
"url": "https://deviens-marrant.fr/vannes/mon-pere-menvoie-ses-messages-en-majuscules-cmmnsqn160?utm_source=widget&utm_medium=embed&utm_campaign=vanne-du-jour&utm_content=inconnu",
"attribution": {
"name": "Deviens Marrant",
"url": "https://deviens-marrant.fr/",
"required": true
},
"license": "https://deviens-marrant.fr/integrer-la-vanne-du-jour#licence"
}Fields
type- "vanne" (French for "joke"). Do not reject the response on this field: treat any other value like "vanne".
date- The day of the joke, in UTC, formatted YYYY-MM-DD. If it is not today's UTC date, your cached copy is stale.
amorce- The setup of the joke. Plain UTF-8 text, no HTML, with French typography: it may contain curly apostrophes (’), French quotation marks (« ») and no-break spaces (U+00A0), for example before colons, semicolons, exclamation marks and question marks, plus an invisible word joiner (U+2060) after the hyphen of some compound words. Strip U+2060 if you search, compare or read the text aloud.
chute- The punchline. Same format as amorce.
url- The public page of the joke on deviens-marrant.fr (in French), which explains why it is funny. The link already carries UTM parameters. Its utm_content value is the domain of the calling site, taken from the Origin header, or from the Referer header when there is no usable Origin (lowercase, without "www."), or inconnu (French for "unknown") when neither header is usable, as with a server-side call or curl.
attribution- An object {name, url, required}. required is always true: a visible "Deviens Marrant" link pointing to that url is mandatory wherever you display the joke (see the License section below).
license- The URL of the terms of use, in French (an English translation is in the License section below).
CORS and caching
CORS is open to all origins: every GET response from the API (200, 403 and 503) and the OPTIONS preflight carry Access-Control-Allow-Origin: *, so you can call it straight from the browser. Responses generated by our CDN, such as the 429 below, have no CORS header.
A successful response normally carries Cache-Control: public, max-age=300, s-maxage=3600, so browsers may reuse it for up to 5 minutes and shared caches for up to 1 hour. Neither lifetime ever extends past midnight UTC: s-maxage is capped at the number of seconds left until midnight during the last hour of the day, and max-age during the last 5 minutes, so a cache that follows these headers does not serve yesterday's joke.
The joke changes every day at midnight UTC and is normally the same for everybody. The rotation draws from a limited set of hand-picked jokes, so jokes come back over time. If we withdraw a joke, the joke of the day can change before midnight UTC.
Rate limit
The limit is 10 requests per 10 seconds per IP address. Beyond that, the address is blocked for 10 seconds: every request gets an HTTP 429 response. When you call the API from the browser, each visitor's requests count against their own IP address; visitors who share one (office, school, mobile carrier) share the limit, so on a busy site prefer a server-side call with your own cache. The joke normally changes only at midnight UTC, so one call a day is enough: cache the response on your side (the license allows up to 24 hours) and refresh it after midnight UTC.
Errors
503- {"type":"vanne","error":"indisponible"} ("unavailable"): no joke can be served right now. The response carries Retry-After: 3600, so wait at least an hour before trying again.
403- {"type":"vanne","error":"acces-refuse"} ("access denied"): the calling site, read from the Origin or Referer header, has been blocked (abuse or inappropriate content, see License and terms).
429- Rate limit exceeded. Wait 10 seconds before the next call. This response comes from our CDN: its body is not JSON and it has no CORS header, so a browser may report it as a network or CORS error.
Privacy
The API sets no cookies and does not track your visitors. Request data, such as the IP address of whoever makes the call (your server, or each visitor's browser if you call the API client-side), is used to serve the response and enforce the rate limit, and may appear in our hosting provider's technical logs. Apart from those technical logs, the domain of the calling site, read from the Origin or Referer header, is used for two things only: checking it against our list of blocked sites, and filling the utm_content parameter of the link, so we can see which sites send clicks. It says nothing about your visitors.
License and terms
Usage license, in short: you may display the joke free of charge, unmodified and without presenting it as your own, on a site, in an app, a bot, an extension or a newsletter, with the “Deviens Marrant” attribution link clearly visible next to it. You may cache it on your side (server or browser) for 24 hours maximum. You may not archive it, copy it in bulk, resell it, put it in a collection or a database of jokes, or use it to train an AI model. Bot messages and newsletters that have already been sent can stay where they are. The service is provided without warranty, and we can cut off your access.
The joke of the day is free of charge: you can display it on your site, in an app, a bot (Discord, Slack, Telegram…), an extension or a newsletter, without asking us. It is provided as is, with no guarantee of availability, and it may change. Wherever you show the joke, display the “Deviens Marrant” attribution link next to it, clearly visible. Do not modify the text of the joke and do not present it as your own. You can display the joke even if your site, app, bot, extension or newsletter carries advertising. However, you may not resell the joke, copy it in bulk, archive it, reuse it in a collection or a database of jokes, or use it to train an AI model. Bot messages and newsletters that have already been sent can stay where they are: what is forbidden is keeping the jokes aside (beyond the 24-hour cache) to reuse them later or gather them together. You may cache the joke on your side (server or browser) for 24 hours maximum. The API sets no cookies and does not track your visitors. We can change or stop the service, and cut off your access (inappropriate content where you display the joke, abuse), at any time.
These terms are a courtesy translation. If they differ from the French original, the French version prevails: https://deviens-marrant.fr/integrer-la-vanne-du-jour#licence
Prefer not to code?
A copy-and-paste widget (iframe or script tag) is available at /integrer-la-vanne-du-jour. That page is in French.
Questions or problems with the API: contact@deviens-marrant.fr.