OpenGlaze API Reference

Current REST API for the Flask app in this repository.

**Base URL:** `http://localhost:8768/api` for Docker, `http://localhost:8767/api` for manual local runs unless `FLASK_PORT` is set.

**Authentication model:** default personal mode is single-user and mostly unauthenticated. Studio collaboration uses the lightweight simple-auth token returned by `/api/auth/simple-login`. Cloud/Ory auth exists in code, but PostgreSQL/cloud mode is not the default launch path.

Health

GET /health
GET /api/health

`/health` returns a basic status/version payload. `/api/health` also reports mode, feature flags, and rate-limit stats.

Auth

Simple login

POST /api/auth/simple-login
Content-Type: application/json

{
  "display_name": "Jane Potter"
}

Response:

{
  "user_id": "u_...",
  "display_name": "Jane Potter",
  "token": "..."
}

Send the token as:

Authorization: Bearer <token>

Current user

GET /api/auth/me
Authorization: Bearer <token>

Glazes

GET /api/glazes
GET /api/glazes/<glaze_id>
POST /api/glazes
PUT /api/glazes/<glaze_id>
DELETE /api/glazes/<glaze_id>
GET /api/glazes/<glaze_id>/umf?cone=10

Create/update payloads use the glaze fields accepted by `Glaze.from_dict`, including `id`, `name`, `family`, `hex`, `chemistry`, `behavior`, `layering`, `warning`, `recipe`, `catalog_code`, `food_safe`, and `notes`.

Combinations

GET /api/combinations
GET /api/combinations?type=research-backed
GET /api/combinations?type=user-prediction
GET /api/combinations/grouped
GET /api/combinations/<combo_id>
POST /api/combinations
PUT /api/combinations/<combo_id>
POST /api/combinations/<combo_id>/promote
POST /api/combinations/<combo_id>/simulate
POST /api/combinations/simulate-all
GET /api/combinations/<combo_id>/compatibility?cone=10

Chemistry

POST /api/chemistry/batch
POST /api/chemistry/scale
POST /api/chemistry/compare
POST /api/chemistry/optimize
POST /api/chemistry/substitutions
POST /api/chemistry/defects

Examples:

POST /api/chemistry/optimize
Content-Type: application/json

{
  "recipe": "Custer Feldspar 45, Silica 25, Whiting 18, EPK 12",
  "target": "reduce_cte",
  "max_suggestions": 5
}

POST /api/chemistry/scale
Content-Type: application/json

{
  "recipe": "Custer Feldspar 45, Silica 25, Whiting 18, EPK 12",
  "batch_size_grams": 1000,
  "unit": "grams"
}

POST /api/chemistry/compare
Content-Type: application/json

{
  "recipe_a": "Custer Feldspar 45, Silica 25, Whiting 18, EPK 12",
  "recipe_b": "Custer Feldspar 40, Silica 30, Whiting 18, EPK 12",
  "name_a": "Original",
  "name_b": "Revision",
  "cone": 10
}

Experiments

GET /api/experiments
GET /api/experiments?stage=ideation
GET /api/experiments/active
GET /api/experiments/stats
GET /api/experiments/<exp_id>
POST /api/experiments
POST /api/experiments/<exp_id>/advance
POST /api/experiments/<exp_id>/result
POST /api/experiments/<exp_id>/archive
POST /api/experiments/<exp_id>/firing-log
POST /api/experiments/<exp_id>/share

Uploads and photos

POST /api/upload
GET /api/photos

Upload expects multipart form-data with a `photo` field. Supported extensions are JPG, JPEG, PNG, and WebP; max size is 5 MB.

Studio collaboration

Studio endpoints require simple-auth or Ory user context.

POST /api/studios
GET /api/studios
POST /api/studios/join
GET /api/studios/<studio_id>
DELETE /api/studios/<studio_id>
POST /api/studios/<studio_id>/regenerate-code
GET /api/studios/<studio_id>/lab-queue
POST /api/studios/<studio_id>/lab-queue/<combo_id>/claim
POST /api/studios/<studio_id>/lab-queue/<combo_id>/release
GET /api/studios/<studio_id>/my-claims
GET /api/studios/<studio_id>/experiments

Progress, stats, and predictions

These endpoints require authenticated user context and may return `401` in default unauthenticated personal mode.

GET /api/stats
GET /api/progress
POST /api/predictions
GET /api/predictions/leaderboard

Templates

GET /api/templates
GET /api/templates/<template_id>
POST /api/templates/<template_id>/apply

Applying a template requires authenticated user context.

Demo endpoints

GET /api/demo/glazes
POST /api/demo/compatibility

These are public demo/reference endpoints backed by curated demo glaze data when available.

Error format

Most errors are returned as JSON:

{
  "error": "Human-readable message"
}

Rate limits return HTTP `429` with a `Retry-After` header.