Research / Undocumented API
How guided-cooking annotations were verified.
Cookidoo’s customer-recipe editor can store more than text. We observed its real requests, reproduced the structures through the authenticated API, and verified that the editor reconstructed them after reload.
Verified finding
Private Cookidoo recipe steps accept positioned TTS, INGREDIENT, and MODE annotations. A temporary recipe round trip reconstructed ingredient weighing, manual time/temperature/speed with reverse, and Dough mode in the authenticated editor. Those annotations also survived a partial step PATCH and reload.
Why research was needed
Readable text did not drive machine settings
A private recipe could display “30 seconds / speed 10,” but plain text alone did not tell Cookidoo to reconstruct a guided setting. The public recipe-details endpoint also omits official preparation instructions. The missing layer was a structured, undocumented annotation contract.
Guessing field names or offsets would risk creating recipes that looked correct in an API response but behaved incorrectly in the editor or on a device.
Method
Observe, reproduce, reload, clean up
- Inspect the authenticated customer-recipe editor.
The deployed editor bundle and its network requests were observed while changing settings on the account’s own private recipe.
- Capture exact request shapes.
This established annotation types, data fields, uppercase mode names, and the relationship between text and
position. - Create a temporary private recipe.
The test target was isolated from existing customer recipes and created only for end-to-end verification.
- Write annotations through the authenticated service.
The recipe received ingredient, manual-setting, and mode structures through the same customer-recipe API used by the editor.
- Reload the editor and inspect reconstruction.
The page rebuilt the corresponding custom elements and exposed their amount, unit, time, temperature, speed, direction, and mode data.
- PATCH and reload again.
A partial instruction update preserved the annotations, proving that a safe steps-only update did not require replacing unrelated recipe fields.
- Delete the temporary recipe.
The verification target was removed after the test so the account was not left with research data.
Round-trip evidence
Three independent action types survived
| Stored structure | Editor reconstruction | What it proved |
|---|---|---|
Step INGREDIENT with nested VOLUME | Ingredient element with amount and unit data | The verified path for on-device weighing is nested inside the step link. |
TTS with 30 seconds, 100 °C, speed 4, and CCW | Manual setting with time, temperature, speed, and reverse | TTS means Time/Temperature/Speed; reverse is explicit. |
MODE named DOUGH with 60 seconds | Dough mode with its duration | Modes use uppercase names and mode-specific data. |
The editor also showed that safe partial updates can send only {"instructions": [...]} or only {"ingredients": [...]}. Cookidoo MCP uses those forms to preserve unrelated recipe fields.
The subtle failure mode
Positions are JavaScript UTF-16 ranges
Every annotation selects a readable phrase inside its step. JavaScript counts UTF-16 code units, while Python normally counts Unicode code points. An emoji before the selected phrase therefore changes the API offset without changing Python’s ordinary index in the same way.
schemas.position_for and the calculate_annotation_position MCP tool encode the text as UTF-16 little-endian and return the correct range.
The Pydantic schemas also reject positions outside their enclosing text and enforce the required separation between ingredient annotations and machine-action annotations.
From finding to product
The research became six reusable safeguards
- Typed Pydantic models for
TTS,INGREDIENT,VOLUME, and supported modes. - UTF-16 position calculation exposed as an MCP tool.
- Whole-recipe validation before upload.
- Partial step and ingredient PATCH operations.
- A verified example recipe for agents and maintainers.
- Unit tests plus scheduled live API contracts for early regression visibility.
What remains uncertain
A verified private contract is still undocumented
- Cookidoo can change endpoints, validation, editor behavior, or feature flags without notice.
- The account did not expose every feature flag during research. A top-level ingredient-list
VOLUMEcould be stripped even though the nested step structure was preserved. - Schema validity does not guarantee that chosen cooking settings are safe or culinarily correct.
- Private customer-recipe behavior should not be described as official Guided Cooking content.
These limits are why documentation uses dates, live tests check the real API, and browser research remains available when a contract genuinely changes.
Authored by the Cookidoo MCP maintainers from the project’s recorded editor observation, round-trip verification, schemas, example payload, and tests. Editor contract observed 23 July 2026; page rechecked 29 July 2026.