pokeapi.co

A PokéAPI Pokémon response is a JSON object returned from https://pokeapi.co/api/v2/pokemon/{name-or-id}. It contains the Pokémon's core attributes (height, base_experience), nested arrays for abilities, forms, game_indices, and held_items, and every related entity is represented as a { "name": ..., "url": ... } pair pointing to another API resource. The example on the PokéAPI homepage for Ditto (https://pokeapi.co/api/v2/pokemon/ditto) shows this structure directly.

The top-level shape

Requesting a Pokémon returns one object whose keys describe different facets of that Pokémon. In the Ditto example, the visible top-level fields include:

The response is not a flat record. It is a graph of references: the Pokémon object tells you what exists, and the URLs tell you where to fetch the details.

How nested references work

Every related resource follows the same pattern: a name plus a url. For Ditto's abilities:

"abilities": [
  {
    "ability": { "name": "imposter", "url": "https://pokeapi.co/api/v2/ability/150/" },
    "is_hidden": true,
    "slot": 3
  },
  {
    "ability": { "name": "limber", "url": "https://pokeapi.co/api/v2/ability/7/" },
    "is_hidden": false,
    "slot": 1
  }
]

The Pokémon endpoint gives you the ability's name and a link. To learn what "limber" actually does, you follow https://pokeapi.co/api/v2/ability/7/. The same applies to forms (.../pokemon-form/132/) and to each version inside game_indices and held_items.

This design keeps the Pokémon response compact while letting you drill into any linked resource on demand.

Reading version-specific data

game_indices and held_items are where the response becomes version-aware.

• game_indices lists the Pokémon's in-game index number for each version. Ditto shows game_index: 132 for most versions but game_index: 76 for red, with each version carrying its own name and url.
• held_items nests a second level: each item has name/url, and inside it a version_details array listing rarity and the version where that hold rate applies. Ditto's metal-powder entry shows rarity: 5 across multiple versions such as moon, x, black-2, and heartgold.

So if your task is "show which items a Pokémon can hold in a specific game," you filter held_items[].version_details[] by the version name rather than reading a single global value.

A practical way to explore it

1. Open the resource URL https://pokeapi.co/api/v2/ and submit a path such as pokemon/ditto, or go directly to https://pokeapi.co/api/v2/pokemon/ditto.
2. Inspect the top-level keys to see which facets exist for that Pokémon.
3. Pick a nested url (for example an ability or version) and request it to resolve the reference.
4. For lists, use query parameters like pokemon?limit=100000&offset=0 to page through the collection.

The homepage also offers hint paths such as pokemon-species/aegislash, type/3, and ability/battle-armor, which are useful for seeing how other resource types compare to the Pokémon shape.

Common points to watch

• Names vs. IDs: endpoints accept either a name (ditto) or a numeric ID, and the returned url fields always use IDs.
• References are not inlined: a url is a pointer, not the data. You must make a second request to get ability text, item details, or version metadata.
• Version nesting: held_items and game_indices are per-version, so aggregate values require iterating their arrays rather than reading one field.
• Field coverage varies: the fields shown for Ditto are the structure to expect, but not every Pokémon will populate every array with the same depth.

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

PokéAPI is a free, open-source RESTful API that serves Pokémon data as JSON over HTTPS. You query a resource URL such as https://pokeapi.co/api/v2/pokemon/ditto and get back a structured record covering that Pokémon's abilities, measurements, game appearances, held items, and more. It is a good fit if you are building a Pokédex, a fan game, a data visualization, or a teaching demo and want a real API with predictable resource paths rather than scraping fan wikis.

What data does it cover?

The API is organized around resource types, each with its own endpoint. The site's own examples point to several of them:

• Pokémon — pokemon/ditto returns a single Pokémon record.
• Species — pokemon-species/aegislash returns species-level data, which is where flavor text, evolution context, and similar entries live.
• Types — type/3 returns a type resource (damage relations and associated Pokémon).
• Abilities — ability/battle-armor returns an ability record.
• Lists — pokemon?limit=100000&offset=0 returns a paginated index of Pokémon.

A single Pokémon response is richer than a name-and-sprite lookup. In the Ditto example on the homepage, the JSON includes:

Note that height and weight use the API's own integer units, not meters or kilograms — check the docs before displaying them to users.

How do you use it?

The interaction model is a plain HTTP GET against a resource URL. There is no key or account step described on the page; the homepage presents the API as "free open-source" and offers a live "Try it now!" box where you paste a resource path and submit.

1. Pick a resource path. Start from the documented examples: pokemon/ditto, pokemon-species/aegislash, type/3, ability/battle-armor.
2. Build the full URL. Prepend the base https://pokeapi.co/api/v2/ to the path. The site provides a copy-to-clipboard button for the base URL and a direct link to results, e.g. https://pokeapi.co/api/v2/pokemon/ditto.
3. Send the request and read the JSON. The response is a JSON object whose nested fields often contain their own url values — those are follow-up resources you can fetch the same way.
4. Page through lists. Use limit and offset on collection endpoints; the site's example uses a very large limit to pull the full Pokémon index in one call.

A minimal check in a terminal:

curl -s https://pokeapi.co/api/v2/pokemon/ditto | head -c 400

Expected result: a JSON object beginning with abilities, base_experience, forms, and so on — the same shape shown in the homepage sample.

What should you watch out for?

• Linked resources, not embedded ones. Fields like ability, version, and item contain a name plus a url. If you need details, you make another request. Plan for this in your data layer so you don't fire requests one at a time in a UI loop.
• Version-specific data. game_indices and held_items vary by game version, so decide up front whether you are showing one version or aggregating across all of them.
• Scale is real. The site states it serves over 50 billion API calls each month. That signals reliability, but it also means you should cache responses locally rather than re-fetching static data like type charts on every page load.
• Units and naming. Slugs are lowercase and hyphenated (battle-armor, metal-powder), and numeric fields use internal units. Normalize both before display.

Is it the right choice for your project?

Choose PokéAPI when you want a documented, resource-oriented REST interface with stable URLs and JSON you can map directly onto models — and when you are comfortable following links between resources. If your project only needs a static snapshot of a few hundred records, fetching once and storing the JSON locally will be simpler and faster than querying live. Either way, start from the docs linked on the homepage and test paths in the "Try it now!" box before wiring them into code.

PokéAPI exposes a set of named REST resources under the base URL https://pokeapi.co/api/v2/, and you reach any record by appending the resource name plus an ID or name — for example pokemon/ditto, pokemon-species/aegislash, type/3, or ability/battle-armor. The site's own "Try it now" box lists these four as sample paths, and its documentation lists the full set of endpoints. If you need a specific resource beyond the examples below, treat the docs as the authoritative index rather than guessing path names.

How the URL pattern works

Every resource follows the same shape:

https://pokeapi.co/api/v2/{resource}/{id-or-name}

• {resource} is the collection name, such as pokemon, pokemon-species, type, or ability.
• {id-or-name} accepts either a numeric ID or a lowercase slug. pokemon/ditto and pokemon/132 both resolve to the same record.
• Collection endpoints also accept pagination parameters. The site's hint shows pokemon?limit=100000&offset=0 as a way to pull a large list in one request.

The expected result of a correct call is a JSON object for that single record; a wrong resource name or unknown ID returns an error rather than a partial object.

Resource examples shown on the site

The pokemon/ditto response is the most fully illustrated example on the page, so it is the best one to inspect first when you want to see the field structure.

Reading a response: the Ditto example

The documented Ditto payload shows how records are shaped and cross-linked:

• Abilities are an array of objects, each with ability.name, ability.url, is_hidden, and slot. Ditto lists imposter (hidden, slot 3) and limber (not hidden, slot 1).
• Cross-links are full URLs, not embedded objects. ability.url points to https://pokeapi.co/api/v2/ability/150/, so following it is a second request.
• Game indices pair a game_index with a version object that itself has a name and url. Ditto's index is 132 in most listed versions but 76 in red.
• Held items nest version_details with a rarity per version — Ditto's metal-powder shows rarity 5 across several versions.
• Scalar fields such as height and base_experience sit at the top level.

The practical takeaway: one call gives you one record, and anything referencing another resource arrives as a URL you must fetch separately. Plan for multiple requests when you need joined data.

Choosing an endpoint for a task

• Building a Pokédex entry → start with pokemon/{name} for stats and abilities, then pokemon-species/{name} for species-level context.
• Type matchup or filter work → use type/{id-or-name}.
• Ability lookup → use ability/{id-or-name}.
• Bulk local dataset → use the collection endpoint with a high limit, as in the site's pokemon?limit=100000&offset=0 hint, then cache results rather than re-requesting per record.

Common snags

• Guessing resource names. Only the documented set is guaranteed; confirm unfamiliar names in the docs before building against them.
• Assuming nested data is inline. Ability, version, and item references are URLs — a single response will not contain the full related object.
• Ignoring pagination. Collection endpoints are list-shaped; without limit/offset you get a page, not everything.
• Case and spacing in slugs. Names in paths are lowercase hyphenated forms like battle-armor, not display names.

The site describes itself as a free open-source RESTful API serving over 50 billion calls per month; no pricing or authentication requirements are stated on the page, so verify access terms in the docs before relying on it for production traffic.

PokéAPI is a free, open-source RESTful API that serves Pokémon data. To start using it, send an HTTP GET request to https://pokeapi.co/api/v2/ followed by a resource path, such as pokemon/ditto or type/3, and you'll receive a JSON response. No API key or authentication is mentioned on the site, so you can begin with a browser or any HTTP client. This guide covers the base URL, your first requests, pagination, and how to explore the rest of the API.

Understand the Base URL and Response Format

Every request starts with the base resource URL:

https://pokeapi.co/api/v2/

Append a resource and identifier to it. The site's own examples include:

Responses are JSON. For example, requesting https://pokeapi.co/api/v2/pokemon/ditto returns an object containing fields such as abilities, base_experience, forms, game_indices, height, and held_items. Nested objects typically include both a name and a url, so you can follow links to related resources without guessing endpoint paths.

Make Your First Request

You can test the API in three common ways.

In a browser

Paste a full URL such as https://pokeapi.co/api/v2/pokemon/ditto into the address bar. The browser displays the raw JSON. This is the fastest way to confirm the API is reachable and to inspect the shape of a response.

With a command-line tool

Using curl:

curl https://pokeapi.co/api/v2/pokemon/ditto

The expected result is the same JSON object printed to your terminal. If you get an error instead, check that the resource path is spelled correctly.

In code

Any HTTP library works. For example, in JavaScript:

const res = await fetch("https://pokeapi.co/api/v2/pokemon/ditto");
const data = await res.json();
console.log(data.name, data.height);

The input is the URL; the action is a GET request; the expected result is a parsed JSON object you can read fields from.

Use Pagination with limit and offset

List endpoints return many records, so PokéAPI supports limit and offset query parameters. The site's hint shows a request for a very large page:

https://pokeapi.co/api/v2/pokemon?limit=100000&offset=0

• limit sets how many records to return.
• offset sets where to start in the list.

To page through results, request a modest limit and increase offset by that amount each time. For example, ?limit=20&offset=0, then ?limit=20&offset=20, and so on. The response for list endpoints typically includes a count of total records plus a next and previous URL, which you can follow instead of building offsets manually.

Explore the Documentation for Full Endpoint Details

The homepage only shows a handful of example paths. For the complete set of resources and the fields each returns, follow the site's "Check out the docs!" link. The docs are where you confirm:

• Which resource names exist and what identifiers they accept (names or numeric IDs).
• The full field list for each response type.
• Any nested resources you may want to fetch next.

A practical workflow is to start from a known example like pokemon/ditto, inspect the url values inside the response, and then request those URLs directly. This lets you move from a Pokémon to its abilities, forms, or game indices without memorizing the endpoint list.

Common Sticking Points

• Wrong path spelling. Resource names are lowercase and hyphenated where needed (for example, pokemon-species, battle-armor). A typo returns an error rather than data.
• Assuming a fixed schema. Fields vary by resource; always inspect the actual response before writing parsing code.
• Fetching everything at once. Large limit values work, but for apps it's usually better to paginate so responses stay manageable.
• Forgetting the trailing structure. The base URL ends in /api/v2/; requests are built by appending paths to it, not by replacing it.

Once you can retrieve pokemon/ditto and page through a list endpoint, you have everything needed to explore the rest of PokéAPI using its documentation and the url links embedded in each response.