canonical: https://jentic.com/apis/blague.xyz/blague

# Blague.xyz API

Jentic publishes the only available OpenAPI specification for Blague.xyz API, keeping it validated and agent-ready. Blague.xyz was a French jokes API offering random joke retrieval, joke lookup by id, and a joke catalogue count. The service appears to be defunct as of 2026 (domain listed for sale), so the spec is best treated as a historical or template reference for similar joke APIs rather than a live integration target. The shape is the standard joke-API pattern: a random endpoint, a by-id endpoint, and a count endpoint.

## For AI agents

Reference spec for a French jokes API: three endpoints for random joke, joke by id, and joke count. Service is defunct as of 2026.

## Scope

Does not handle live joke retrieval after the 2026 shutdown, joke submission, or moderation - use for historical Blague.xyz schema reference only.

## Capabilities

- Pull a random French joke from the Blague.xyz catalogue
- Look up a specific French joke by its numeric id
- Retrieve the total count of jokes available in the catalogue
- Reuse the spec as a template for similar joke or content APIs
- Reference the bearer-auth pattern when designing a comparable hobby API

## Use cases

### French Joke Retrieval Reference

Reference the Blague.xyz spec when designing a French-language joke or trivia feature. The three endpoints (GET `/joke/random`, GET `/joke/{id}`, GET `/joke/count`) cover the canonical joke-API shape: pick a random item, fetch a specific item, and report the catalogue size. The schema is a useful starting point for a similar feature backed by another data source.

Example prompt: Read the GET `/joke/random` response schema from the spec and use it to model the response shape of a comparable joke service.

### Migration Audit for Former Users

Teams that previously called Blague.xyz can use the spec to inventory their existing call sites, then map each operation to a live alternative joke API. The path-and-method list makes it straightforward to grep a codebase for impacted lines and produce a migration checklist without reading the original integration code in full.

Example prompt: List every operationId in the Blague.xyz spec and propose a corresponding endpoint on a live joke API for each.

### Hobby Project Bootstrap

Use the Blague.xyz spec as a tiny, three-endpoint bootstrap example when teaching API design or building a hobby project that mirrors a 'fun content' service. Bearer auth, a random endpoint, an id endpoint, and a count endpoint together form a minimal teaching artefact for OpenAPI structure and bearer-token security schemes.

Example prompt: Use the Blague.xyz paths as a template for a new OpenAPI document that exposes random, by-id, and count endpoints for any small content corpus.

### Agent Schema Lookup via Jentic

An AI agent searching for a 'random joke' tool finds Blague.xyz in Jentic and inspects its schema, even though the live service is offline. This is useful in eval and template scenarios where the agent needs an example of a small, well-formed API to reason about. Jentic returns the spec contents without attempting a live call when the upstream is dead.

Example prompt: Use Jentic search for 'get a random French joke', load the GET `/joke/random` schema, and use the schema to populate a fixture for an agent eval.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/joke/random` | Get a random French joke |
| GET | `/joke/{id}` | Get a joke by id |
| GET | `/joke/count` | Get the total joke count |

## Key resources

- **Joke** — Random joke retrieval, joke lookup by id, and total catalogue count

## Why Jentic

- **Setup:** Blague.xyz is defunct, so wiring it by hand would still mean building the bearer Authorization header and targeting the api.blague.xyz host only to reach a dead endpoint. Through Jentic you install once, import Blague.xyz from the API Directory as a schema reference, and your agent reads the archived operations instead of attempting a live call.
- **Permission scoping:** Blague.xyz exposes read joke endpoints, with the joke id in the URL path (`/joke/{id}`), so limit the agent to the operations it needs, such as reading a random joke or a joke count. You choose the operations it may call, and because the service is defunct there is nothing live to reach.
- **Credential handling:** The former Blague.xyz bearer token would be stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context, though the endpoint is no longer live.
- **Discovery method:** Agents search Jentic by intent such as 'get a random French joke', and Jentic returns the GET `/joke/random` operation with its schema so the agent reads the reference without browsing the docs.

## Related APIs

- **BizToc** — BizToc supplies live business news content while Blague.xyz supplied joke content - both are simple content APIs.
- **Bitskout Zapier API** — Bitskout processes documents while Blague.xyz returned joke content - both are tiny single-purpose APIs.
- **Blastable** — Blastable is an email marketing API, unrelated in domain but similar in being a small focused service.

## FAQ

### Why is there no official OpenAPI spec for Blague.xyz API?

Blague.xyz did not publish an OpenAPI specification, and the service appears to be defunct as of 2026 with the domain listed for sale. Jentic generates and maintains this spec so AI agents and developers can reference the historical interface via structured tooling. Get started with Jentic One, the self-hosted execution layer.

### Is the Blague.xyz API still live?

No. The service appears to be defunct as of 2026 - the domain is reportedly for sale. Treat the spec as a historical or template reference rather than a live integration target.

### What authentication does the Blague.xyz API use?

The spec declares HTTP bearer authentication (security scheme bearerAuth). When the service was live, callers attached a bearer token in the Authorization header. Through Jentic the token would be stored in the encrypted vault, but live calls are no longer expected to succeed.

### Can I get a random joke from the Blague.xyz API?

GET `/joke/random` was the live endpoint. Calls against the production base URL are unlikely to succeed because the service is defunct, but the schema in the spec describes the response shape if you have an archived dataset.

### What are the rate limits for the Blague.xyz API?

The OpenAPI spec does not declare a rate limit. Since the service is no longer live, this is moot - any rate-limit handling would only matter if a successor service adopted the same shape.

### How do I use the Blague.xyz spec through Jentic?

Install with pip install jentic, then use Jentic search with 'get a random French joke'. Jentic returns the GET `/joke/random` operation and its schema, which you can use as a template or in eval scenarios even though the live endpoint is no longer reachable.

### Can I limit what my agent is allowed to do with the Blague.xyz API?

Yes. Because you run Jentic One yourself, your own rules decide which Blague.xyz operations the agent may call and which credentials it may use. This API only exposes read joke endpoints, so you can allow just the ones the agent needs, such as GET `/joke/random` or GET `/joke/count`, and withhold lookup by id (GET `/joke/{id}`). The agent can never reach any operation you have not granted it.