canonical: https://jentic.com/apis/arno-di-loreto.github.io/api-stylebook

# Arno Di Loreto API Stylebook's API

Jentic publishes the only available OpenAPI specification for API Stylebook's API, keeping it validated and agent-ready. The API Stylebook serves curated API design guidelines and topics drawn from public style guides published by API teams. Six endpoints expose lists of guidelines and topics, plus the cross-references between them, in JSON or HTML formats. The API is read-only and unauthenticated, intended for tooling that surfaces API design guidance during reviews and architectural decisions.

## For AI agents

Look up API design guidelines and topics from the API Stylebook so an agent can cite established design conventions during API reviews.

## Scope

Does not lint OpenAPI specs, validate JSON Schema, or modify guidelines - use for read-only lookup of API Stylebook guidelines and topics only.

## Capabilities

- List all curated API design guidelines
- Fetch a specific guideline by id with its referenced topics
- List API design topics covered across the stylebook
- Fetch a topic by id and discover the guidelines that address it
- Switch between JSON and HTML representations via the {format} path parameter

## Use cases

### API Review Citation Helper

During pull request reviews on an OpenAPI spec, surface relevant API Stylebook guidelines for topics like error formats, pagination, and versioning. The `/design/topics.{format}` and `/design/topics/{topicId}/guidelines.{format}` endpoints return cross-references so a review bot can cite published industry guidance instead of relying only on the reviewer's memory.

Example prompt: Fetch `/design/topics.json`, find the topic id for 'pagination', then GET `/design/topics/{topicId}/guidelines.json` and post the matching guideline links as a PR comment

### Design Decision Brief

Generate a short brief on how leading API teams handle a design topic by pulling all guidelines for that topic from `/design/topics/{topicId}/guidelines` and summarising them. Useful when an architect is deciding on a convention and wants prior art rather than first-principles debate.

Example prompt: Pull all guidelines for the topic id matching 'errors', then synthesise a one-page brief comparing the recommended error response shapes

### Stylebook Mirroring

Mirror the API Stylebook content into an internal developer portal by paginating `/design/guidelines.json` and `/design/topics.json` on a schedule and pushing the results into a search index. This keeps internal API reviewers offline-friendly without scraping HTML pages.

Example prompt: GET `/design/guidelines.json` and `/design/topics.json`, normalise the responses, and upsert them into the company's internal search index

### Agent Design Coach via Jentic

Wire an AI design-review agent so that when it inspects an OpenAPI spec it can call the API Stylebook through Jentic to fetch relevant guidelines on the fly. The agent searches Jentic for 'list API design topics', loads the schema, and looks up matching guidance per finding.

Example prompt: Search Jentic for 'list API design topics', load the schema for `/design/topics.json`, and resolve the topic id for 'versioning' before recommending guidelines to the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/design/guidelines.{format}` | List all guidelines |
| GET | `/design/guidelines/{guidelineId}.{format}` | Fetch a guideline by id |
| GET | `/design/guidelines/{guidelineId}/topics.{format}` | List topics referenced by a guideline |
| GET | `/design/topics.{format}` | List all topics |
| GET | `/design/topics/{topicId}.{format}` | Fetch a topic by id |
| GET | `/design/topics/{topicId}/guidelines.{format}` | List guidelines covering a topic |

## Key resources

- **Guidelines** — List and fetch curated API design guidelines from public style guides
- **Topics** — List and fetch API design topics with cross-references to guidelines

## Why Jentic

- **Setup:** Wiring API Stylebook's API by hand means resolving its GitHub Pages host and handling the {format} suffix on every guideline and topic path yourself, even though there are no credentials to manage. Through Jentic you install once, import API Stylebook's API from the API Directory, and your agent calls it with no key to configure.
- **Permission scoping:** This is a read-only lookup API with no write operations, so a rule can limit the agent to the operations it needs, such as listing guidelines or fetching a single topic. You choose the operations it may call, and since the spec exposes only GET reads, nothing can modify guidelines.
- **Credential handling:** API Stylebook's API is unauthenticated, so there is no credential to store. Jentic still routes the call through your own Jentic One instance at execution time for consistent handling alongside authenticated APIs.
- **Discovery method:** Agents search Jentic by intent such as 'list API design topics' or 'read a design guideline', and Jentic returns the matching API Stylebook operation with its input schema so the agent calls the right endpoint without browsing the GitHub Pages site.

## Related APIs

- **GitHub API** — GitHub hosts the OpenAPI specs and PRs that an API Stylebook agent would review
- **GitLab API** — GitLab plays the same role as GitHub for teams hosting their API specs there
- **Notion API** — Notion hosts the internal style guide pages that complement the public API Stylebook

## FAQ

### Why is there no official OpenAPI spec for API Stylebook's API?

The API Stylebook does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call API Stylebook's API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the API Stylebook's API require?

None. The API is read-only and unauthenticated. You can call the endpoints directly. When used through Jentic, no credential entry is needed in the vault for this API.

### Can I get the API Stylebook content as JSON?

Yes. Every endpoint accepts a {format} path parameter; pass 'json' (e.g. `/design/guidelines.json`) to get JSON, or 'html' for the rendered page.

### What are the rate limits for the API Stylebook's API?

The site is hosted on GitHub Pages, so it inherits GitHub Pages bandwidth limits (effectively soft, but heavy scraping is discouraged). Cache responses locally rather than calling per request.

### How do I find guidelines on a specific design topic through Jentic?

Run pip install jentic, then search Jentic with 'list API Stylebook topics', load the schema for GET `/design/topics.json`, find the matching topic id, and call GET `/design/topics/{topicId}/guidelines.json` to fetch the cross-referenced guidelines.

### Can I look up which topics a specific guideline covers?

Yes. GET `/design/guidelines/{guidelineId}/topics.{format}` returns the topics referenced by that guideline, which is useful for building reverse indexes.

### Can I limit what my agent is allowed to do with the API Stylebook's API?

Yes. Because Jentic One is self-hosted, you run it yourself and your own rules decide which of the API Stylebook's operations your agent may call, so you can restrict it to just the reads it needs, such as listing guidelines or fetching a single topic by id. Since this API exposes only GET operations and no write endpoints, nothing your agent calls can modify guidelines or topics. Every call is routed through your own Jentic One instance at execution time, so the operator stays in control of the exact operations the agent is allowed to use.