API & registry reference

OPF default catalog

PPTX.gallery publishes the default catalog that OPF catalog references resolve against. Every record validates against its OPF companion schema; gallery-only metadata sits in an x-gallery member. Use these endpoints to resolve ids such as narrative or design.theme.

GET /<kind> with Accept: application/json returns the same index; GET /<kind>/<id>.json returns one record. The index carries contentSha256, the SHA-256 of the canonical JSON of its records without x-* members. OPF engines use the pinned snapshot bundled in @openpresentation/opf and do not fetch these URLs by default.

Catalog JSON endpoints

These envelopes carry the gallery's presentation data in its own shape; they are not OPF records. Each live gallery dimension is exposed as a static JSON endpoint. Responses use a shared catalog envelope with version, dimension, and items at minimum, plus dimension-specific supporting data (best practices, categories, legacy aliases).

Envelope shape

{
  "version": "1.0",
  "dimension": "color-schemes",
  "items": [ ... ],
  "name": "Color Schemes",
  "description": "...",
  "routes": {
    "web": "https://www.pptx.gallery/colors",
    "api": "https://www.pptx.gallery/api/color-schemes.json"
  },
  "opfSchema": {
    "name": "design.colors.scheme",
    "url": "https://openpresentation.org/schema/opf/v1#/$defs/ColorScheme/properties/scheme"
  }
}

Legacy aliases redirect with HTTP 308: /api/colors.json → /api/color-schemes.json, /api/typography.json → /api/font-schemes.json, and /api/social-platforms.json → /api/socials.json.

Font replacement data is additive: /api/font-replacements.json lists, for every family a font scheme names, its license class and its open replacement (metric-compatible, look-alike only, none identified yet, or the open font itself), with the OPF core commit and policy sha256 it was imported from. The same per-role data appears as fontReplacements in /api/font-schemes.json and as metadata.font_replacements in font-scheme registry descriptors; scheme records gain one field, webFontPackages (the bundled, pinned font packages behind a scheme's web font families, for example @fontsource-variable/roboto@5.3.0), and webFontUrl is now always null: the gallery no longer mirrors a font CDN stylesheet URL. OPF exports name the selected font (opf-pptx 0.10.0 and later; earlier releases wrote the substitute), so policy.pptxExport.availableFrom and caveat are null and a role's powerpointExport carries only the selected family.

OPF registry

The registry is the delivery contract for OPF design choices — the shadcn-style mechanism that CLIs and agents read to inject OPF into a deck. The canonical index lives at /registry.json; each item has a descriptor at /registry/{category}/{slug}.json.

Index shape

{
  "$schema": "https://pptx.dev/schema/registry.schema.json",
  "opf_version": "1.0",
  "items": [
    {
      "name": "hero-split",
      "type": "registry:layout",
      "registry_url": "https://www.pptx.gallery/registry/layouts/hero-split.json",
      "dependencies": [],
      "opf_version": "1.0"
    }
  ]
}

Registry categories

• layouts — registry:layout (459 descriptors)
• color-schemes — registry:color-scheme (14 descriptors)
• font-schemes — registry:font-scheme (89 descriptors)
• backgrounds — registry:background (6 descriptors)
• narratives — registry:narrative (48 descriptors)
• charts — registry:chart (27 descriptors)
• themes — registry:theme (4 descriptors)

Descriptor fields

The registry format is open: third parties can publish their own registry.json (e.g. a brand-team OPF registry) using the same schema, and downstream tools can consume it interchangeably. Breaking changes to the format require a version bump and a migration path.

Discovery endpoints

• /llms.txt — full machine-readable catalog index for LLMs and AI agents: every dimension, item, JSON endpoint, and registry descriptor.
• /sitemap.xml — every catalog page and how-to article.
• /api/search-index.json — prebuilt search index over all gallery items, dimensions, and articles (title, href, group, description, keywords). The same index powers the site’s ⌘K search.

The stable-slug contract

• Every gallery item has a stable, human-readable slug (e.g. color-scheme/corporate-trust) that OPF documents reference by name. Renaming a slug is a breaking change across the ecosystem.
• Detail pages follow /{dimension}/{slug}; legacy routes (/colors, /typography) remain for SEO continuity.
• Responses are static and cacheable; endpoints send Cache-Control headers and are safe to fetch at build or generation time.
• No authentication, no rate limiting, no accounts. The catalog is a public good.

See also