Catalog exports

Export curated reference datasets or use catalog values in generated tables. Catalogs provide curated datasets such as countries, languages and currencies. Export a catalog directly for a fixture file, or select catalog values in a recipe when generated records need real codes. Catalog exports cost one credit per row. GBDDL validation and pricing are shared across Chef, the HTTP API and MCP. Consult the recipe language, output formats, and credit model for the supported syntax and behavior.

Discover available types, columns, filters, language coverage and source/license metadata at GET /catalog. Exports support JSON, CSV and TOON. Filters depend on the dataset and may include language, group, parent, country, gender or vocabulary kind.

Call POST /api/v1/catalog/{type}/estimate before POST /api/v1/catalog/{type}/export; API keys need catalog:read. The export returns file bytes directly, rather than a generation-job identifier. It costs one credit per returned row, with a one-credit minimum. Follow the OpenAPI contract for request options and spending headers. Review each dataset's source/license metadata before redistributing it; some vocabulary is pending native-speaker review.

The request selects output_format (json, csv or toon) in the query and can include JSON fields language, columns, filters, limit, sample and seed. Sampling with an explicit seed is reproducible; this catalog option is separate from recipe generation, which has no public seed. A sampled download reports X-Catalog-Seed. X-Max-Cost is an optional ceiling for catalog exports; Idempotency-Key protects retries for seven days. Without an explicit sampling seed, a replay may return different rows even though it does not charge again.