Technical documentation

Modern Mazer Protocol v1

Experimental. This is an experimental v1 protocol specific to Modern Mazer. It is not an established Internet standard. Endpoints are versioned under /api/v1. Breaking changes may occur before a stable v2 is declared.

What Modern Mazer exposes

Modern Mazer is a creator-owned fermentation and mead publishing platform structured for both human readers and machine agents. Every public recipe is available as:

A human-readable HTML page at /recipes/:slug
A machine-readable JSON record at /api/v1/recipes/:slug
A legacy JSON alias at /recipes/:slug.json

All representations originate from the same canonical record. There are no separate, conflicting copies of recipe data.

How agents discover Modern Mazer

Start with the discovery manifest:

GET /.well-known/modern-mazer.json

The manifest identifies all available endpoints, content types, supported actions, and the rights record. It is the authoritative entry point for automated discovery.

API endpoints

GET/api/v1/creator

Creator identity record — name, expertise, organization relationships, rights, correction policy.

GET/api/v1/content-types

Available content types and their collection endpoints. Currently: recipe.

GET/api/v1/recipes

Paginated recipe collection. Supports filtering by style, difficulty, testingStatus, sweetnessLevel, abvMin, abvMax, tag, updatedSince. Ordered by updatedDate DESC.

GET/api/v1/recipes/:slug

Individual recipe in the full protocol envelope. Supports optional scaling via ?targetVolume=&targetUnit= (gallons|liters). Canonical data is never overwritten.

GET/api/v1/search

Deterministic structured search. Supports q, type, ingredient, category, abvMin, abvMax, sweetness, testingStatus, creator, updatedSince, limit, cursor. No generative model.

GET/api/v1/changes

Change feed ordered by updatedAt DESC. Supports since (ISO 8601), type, limit, cursor. Public change summaries only — no private notes.

GET/api/v1/rights

Machine-readable rights and attribution record.

Content envelope schema

Every content record is wrapped in a universal envelope:

{
  protocolVersion: string,      // e.g. "1.0"
  id: string,                   // stable content ID
  type: ContentType,            // "recipe" | "tutorial" | ...
  slug: string,
  canonicalUrl: string,
  machineUrl: string,
  title: string,
  summary: string,
  creator: CreatorIdentity,
  ownership: OwnershipRecord,
  provenance: ProvenanceRecord,
  evidence: EvidenceRecord[],
  testingStatus: string,
  publicationStatus: string,
  version: string,
  createdAt: string,            // ISO 8601
  updatedAt: string,            // ISO 8601
  language: string,
  tags: string[],
  relationships: ContentRelationship[],
  rights: RightsRecord,
  actions: AgentAction[],
  data: T                       // content-type-specific payload
}

Provenance model

Every published recipe tells an agent exactly what it knows and how it knows it. Testing status values are never collapsed into a generic confidence label:

production-provenConfirmed commercial production record from Chapter 11 Cellars.

pilot-testedPhysically produced at pilot scale with recorded results.

owner-formulatedFormulated by the owner but not yet confirmed in production.

developmentDerived from an established platform; requires testing.

conceptEarly-stage idea without a validated formulation.

Evidence model

Each record includes explicit evidence objects. Evidence types:

production-recordConfirmed production record.

pilot-recordPilot-scale production record.

owner-statementOwner formulation or statement.

published-sourcePublished reference source.

calculationDerived by calculation from a known platform.

editorial-inferenceEditorial development; no production record.

Relationship types

derived-fromvariation-ofuses-techniqueuses-ingredientsupported-byauthored-byreviewed-byrelated-tosupersedessold-as

Relationships to private records are never exposed.

Error formats

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": "Optional additional context"
}

HTTP status codes are accurate: 200 success, 400 invalid parameters, 404 not found, 429 rate limited, 500 server error.

Versioning and deprecation policy

The protocol version is included in every response as schema.version. A MAJOR version bump indicates a breaking change. A MINOR bump is additive and backward-compatible.

Deprecated endpoints will be announced with at least 90 days notice before removal. The legacy /recipes/:slug.json endpoint is maintained as a compatibility alias and will not be removed without notice.

Discovery manifest Creator record Recipe collection Rights and attribution