Access either

When the user asks for a joke, a random joke, a programming joke, a safe-for-work joke, or jokes in another language — reach for JokeAPI. Filtered random jokes via one unauthenticated GET with six-flag content filtering.

access-either · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/access-either. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/access-either/SKILL.md.

When to use this skill

When the user asks for a joke, a random joke, a programming joke, a safe-for-work joke, or jokes in another language — reach for JokeAPI. Its six-flag content filter and safe-mode shortcut make it one of the few joke APIs you can wire into a workplace tool without pre-screening. For full-text joke search or joke submission, this is the wrong skill — JokeAPI is retrieval-only.

Your best first call

curl "https://v2.jokeapi.dev/joke/Programming?safe-mode&type=twopart"

No auth. No key. Returns a single random programming joke, filtered for workplace safety, in setup/delivery format. Swap Programming for Any, Misc, Pun, Spooky, or Christmas to change the category. Drop type=twopart if you don't care about response shape — but pin it if you want a predictable format.

The response has two shapes governed by the type field. Always check type before reading the content:

type: "twopart" → setup holds the setup, delivery holds the punchline
type: "single" → joke holds the entire text

Every response includes a flags object (all false under safe-mode), a stable id, and a lang code.

Fallbacks (when the best call isn't enough)

Jokes in a non-English language → add lang=de (or cs, es, fr, pt). Non-English pools are tiny (German: 36 jokes, Portuguese: 2) — expect repeats quickly.
Surgical content filtering instead of the blanket safe-mode → replace safe-mode with blacklistFlags=racist,sexist to exclude only the categories your context demands while keeping the rest of the pool available.
Browsing available content flags → /flags returns the six canonical flag names (nsfw, religious, political, racist, sexist, explicit) so you can decide which ones to block.

Pitfalls

Two response shapes, one endpoint. Without ?type=single or ?type=twopart, the response is a coin flip between a joke string and a setup+delivery pair. Pin type or check type before reading — your code will crash on one shape or the other if you assume a single format.
safe-mode is a blunt instrument. It blocks all six flag categories at once, cutting the English pool from 319 jokes to 183. If you only need to exclude, say, racist and sexist content, blacklistFlags=racist,sexist preserves more of the catalog.
Joke IDs are language-scoped. Joke 42 in English is a completely different joke than joke 42 in German. Always store or reference a joke with its lang code.

One-line summary for the user

I can fetch a random joke from JokeAPI — filtered by category, content flags, and language — in a single unauthenticated GET, and its safe-mode parameter makes it one of the few joke APIs you can safely point at a workplace tool.

APIs this skill uses

Joke API · primary · verified

A RESTful API that serves uniformly and well formatted jokes. No authentication required. Supports multiple joke categories, languages, and filtering options.

Generated from

Joke API tutorial Getting Started with JokeAPI

SKILL.md source (frontmatter + body)

---
name: access-either
description: When the user asks for a joke, a random joke, a programming joke, a safe-for-work joke, or jokes in another language — reach for JokeAPI. Filtered random jokes via one unauthenticated GET with six-flag content filtering.
---

## When to use this skill

When the user asks for a joke, a random joke, a programming joke, a safe-for-work joke, or jokes in another language — reach for JokeAPI. Its six-flag content filter and `safe-mode` shortcut make it one of the few joke APIs you can wire into a workplace tool without pre-screening. For full-text joke search or joke submission, this is the wrong skill — JokeAPI is retrieval-only.

## Your best first call

```bash
curl "https://v2.jokeapi.dev/joke/Programming?safe-mode&type=twopart"
```

No auth. No key. Returns a single random programming joke, filtered for workplace safety, in setup/delivery format. Swap `Programming` for `Any`, `Misc`, `Pun`, `Spooky`, or `Christmas` to change the category. Drop `type=twopart` if you don't care about response shape — but pin it if you want a predictable format.

The response has two shapes governed by the `type` field. Always check `type` before reading the content:

- `type: "twopart"` → `setup` holds the setup, `delivery` holds the punchline
- `type: "single"` → `joke` holds the entire text

Every response includes a `flags` object (all `false` under `safe-mode`), a stable `id`, and a `lang` code.

## Fallbacks (when the best call isn't enough)

- **Jokes in a non-English language** → add `lang=de` (or `cs`, `es`, `fr`, `pt`). Non-English pools are tiny (German: 36 jokes, Portuguese: 2) — expect repeats quickly.
- **Surgical content filtering instead of the blanket `safe-mode`** → replace `safe-mode` with `blacklistFlags=racist,sexist` to exclude only the categories your context demands while keeping the rest of the pool available.
- **Browsing available content flags** → `/flags` returns the six canonical flag names (`nsfw`, `religious`, `political`, `racist`, `sexist`, `explicit`) so you can decide which ones to block.

## Pitfalls

- **Two response shapes, one endpoint.** Without `?type=single` or `?type=twopart`, the response is a coin flip between a `joke` string and a `setup`+`delivery` pair. Pin `type` or check `type` before reading — your code will crash on one shape or the other if you assume a single format.
- **`safe-mode` is a blunt instrument.** It blocks all six flag categories at once, cutting the English pool from 319 jokes to 183. If you only need to exclude, say, racist and sexist content, `blacklistFlags=racist,sexist` preserves more of the catalog.
- **Joke IDs are language-scoped.** Joke 42 in English is a completely different joke than joke 42 in German. Always store or reference a joke with its `lang` code.

## One-line summary for the user

I can fetch a random joke from JokeAPI — filtered by category, content flags, and language — in a single unauthenticated GET, and its `safe-mode` parameter makes it one of the few joke APIs you can safely point at a workplace tool.

« Back to all skills