The xkcd API exposes exactly two ways to retrieve comics: fetch the latest one, or fetch a specific comic by its numeric id. The critical concept is the comic num — that numeric identifier is the canonical key for every comic and is the value you supply as comicId when retrieving a specific comic. Use the current-comic operation to discover the highest available num and then request any comic by that id.

Domain overview

Comics are represented as a single resource type, Comic. Each Comic includes a canonical numeric identifier (num), an image URL (img), a short title, the mouse-over text (alt), and a textual transcript when available, plus date fields. There are no collection/list/search endpoints: the API does not return lists of comics or support text search. The only ways to get comics are:

• the latest comic: getCurrentComic — use this to learn the newest num; and
• a specific comic by id: getComicById with parameter comicId set to the comic's num.

Because num is the canonical id, treat it as the primary reference whenever a user asks for a particular comic.

Entry points — what to call first

When a user does not supply a comic number, call getCurrentComic first. The response includes the latest comic's num, which serves two purposes: it is the maximum valid id currently available, and it provides the latest comic's content directly. When a user supplies a number, call getComicById with comicId equal to that number.

If a user asks for a random comic or a comic within a range and no id is provided, obtain num from getCurrentComic and then pick ids within the range [1, num] (or the requested sub-range) and call getComicById for each id you want to retrieve.

Common tasks and the sequence of calls

These are the workflows that users request most often and exactly how to accomplish them with the available operations.

• Show the latest comic (title, image, alt text): call getCurrentComic. Use the returned img for the image, title for the title, and alt for the mouse-over text.

• Show a specific comic by number: call getComicById with comicId equal to the number the user gave. The returned num confirms the canonical id, and img, alt, title, and transcript provide the comic content.

• Get a random comic: first call getCurrentComic to read the current num. Then pick an integer within [1, num] and call getComicById with that comicId.

• Build a simple gallery or range of comics (for example, comics 100–110): there is no batch/list endpoint. For each id in the requested range, call getComicById with that specific comicId. Request each id you need individually.

• Provide an accessible text fallback: prefer the transcript field when present. If transcript is empty or missing, use alt as a short description and include the title and num.

Non-obvious details and gotchas

• The authoritative way to discover valid ids is getCurrentComic. Do not assume a fixed maximum; call getCurrentComic when you need the current highest num.

• There is no search, listing, or batch-download capability. Any request for multiple comics requires separate getComicById calls for each comicId requested.

• Some comics may have an empty or missing transcript. Treat transcript as optional content. Use alt for concise descriptions and transcript when a fuller textual representation is required.

• Use the num field returned in any Comic as the canonical comicId for future requests or references. Do not infer ids from dates or other fields.

• When a requested comicId is not available, fall back to confirming the latest num via getCurrentComic and then choose a nearby id if appropriate. The API exposes no search to locate comics by keyword or date.

• Image delivery: the img field is the direct image URL to show to users. The API returns the URL; the image itself is hosted elsewhere.

Short checklist for common user intents

• If user asks for "latest" → call getCurrentComic.
• If user gives a number → call getComicById with comicId equal to that number.
• If user asks for a random or ranged selection → first call getCurrentComic to get num, then call getComicById for each chosen id.
• If user needs text (for accessibility or search) → prefer transcript, fall back to alt and title.

These patterns cover the practical ways to satisfy user requests with the xkcd API. The domain is intentionally small: find the right num, then fetch the comic by that id.