API reference

The engine behind the recipe builder is available over HTTPS at https://api.ghostbakery.com. Every endpoint, schema and example is in the interactive reference; this page is the map.

Authentication

Send a bearer credential in the Authorization header:

header

Authorization: Bearer <API key or token>

API keys (grd_…) are for scripts and CI. Create them in your account under API keys: pick the scopes, a validity from one hour to 90 days, and a lifetime credit cap. The key is shown once. Revoke it there at any time.
Tokens come from POST /api/v1/auth/token with your e-mail and password (and a TOTP code at /api/v1/auth/token/mfa when MFA is on). Use them for interactive tools, not for automation.

Scopes

Scope	Allows
`generate`	Estimating and enqueuing generation jobs.
`jobs:read`	Reading job status and downloading results.
`recipes:read`	Listing and reading saved recipes.
`recipes:write`	Creating, updating and deleting saved recipes.
`catalog:read`	Estimating and downloading catalog exports.

Give each key only the scopes its job needs. A key never manages other keys or the account.

Endpoints

Method	Path	Scope	Purpose
`POST`	`/api/v1/estimate`	`generate`	Validate a recipe and return its cost and your balance. Body: the YAML recipe.
`POST`	`/api/v1/generate`	`generate`	Validate, charge and enqueue a job. Returns `job_id`.
`GET`	`/api/v1/jobs/{id}`	`jobs:read`	Job status: `queued`, `processing`, `completed`, `failed` or `expired`.
`GET`	`/api/v1/jobs/{id}/download`	`jobs:read`	The result file of a completed job.
`GET`	`/api/v1/recipes`	`recipes:read`	Saved recipes.
`POST`	`/api/v1/recipes`	`recipes:write`	Save a recipe.
`GET` `PUT` `DELETE`	`/api/v1/recipes/{id}`	`recipes:read` / `recipes:write`	Read, replace or delete a saved recipe.
`GET`	`/catalog`	—	Catalog description: types, columns, groups, output languages and downloadable datasets.
`POST`	`/api/v1/catalog/{type}/estimate`	`catalog:read`	Price a catalog export.
`POST`	`/api/v1/catalog/{type}/export`	`catalog:read`	Charge and download a catalog export as `json`, `csv` or `toon`.

estimate and generate take the YAML recipe as the raw request body, with Content-Type: application/x-yaml. Results are kept for a limited time after the job completes; after that the job reports expired.

Contract and tooling

Resource	URL	Purpose
Interactive reference	https://api.ghostbakery.com/docs	Explore and try every endpoint in the browser.
OpenAPI 3.1 (JSON)	https://api.ghostbakery.com/openapi.json	Canonical machine-readable contract.
OpenAPI 3.1 (YAML)	https://api.ghostbakery.com/openapi.yaml	The same contract in YAML.
OpenAPI 3.0 (JSON)	https://api.ghostbakery.com/openapi-3.0.json	Converted for tools that do not read OpenAPI 3.1 yet.
OpenAPI 3.0 (YAML)	https://api.ghostbakery.com/openapi-3.0.yaml	YAML form of the 3.0 conversion.
JSON Schema	`https://api.ghostbakery.com/schemas/{schema}.json`	One response schema; `{schema}` is a component name from the OpenAPI document.

JSON responses carry a Link header and a $schema property pointing at their schema, so editors and clients can discover it automatically. Errors follow RFC 9457 problem details, with per-key errors for validation failures.

The API applies scope checks, request-size limits, rate limiting on sign-up and token exchange, and restricted CORS. Keep keys out of source control and logs.