> Production API availability: use /api/v1/help?view=guides and the resource operations catalog before following a recipe. Some localhost capabilities are not deployed yet; an absent operation is unavailable.
Make the smallest useful change
Read the current board first. Save that response for review and rollback. Prepare a patch that changes one section or one contract. Avoid replacing the complete board JSON for ordinary editing.
This example changes a header on a board that already contains menu.guide_intro.header. Replace REPLACE_WITH_BOARD_ID with the selected board's ID. The requested source path must exist.
{
"type": "antsand.databoard.patch_delta",
"version": 1,
"source_bundle": "agent",
"agent_intent": {
"requested_outcome": "Clarify the guide introduction heading",
"change_scope": "databoard_content",
"target_board_id": "REPLACE_WITH_BOARD_ID",
"owner": "Databoard presentation header",
"inspected_paths": ["databoard.menu.guide_intro", "databoard.list"],
"policy_contract": "Mapped menu header supplies the existing section",
"runtime_change_required": false,
"runtime_gap": "",
"acceptance_checks": ["The guide renders the revised heading"]
},
"patches": [
{
"id": "guide-heading",
"category": "content",
"status": "safe",
"title": "Revise introduction",
"operations": [
{
"op": "update_menu_field",
"menu_key": "guide_intro",
"path": ["header", "h1"],
"value": "Build one section at a time"
}
]
}
]
}Inspect and validate through HTTP
Use GET /api/v1/databoards/{id}/agent-context and GET /api/v1/databoards/{id}/page-flow with your scoped Bearer key. Read the returned design contract and existing structure before preparing the patch above.
POST the patch envelope as JSON to /api/v1/databoards/{id}/patch/dry-run. Both the direct envelope and an object containing patch_delta are accepted. Inspect success, applied_operations, set_paths and design_review. A successful dry-run does not override a blocking design finding.
After review, POST the same envelope to /api/v1/databoards/{id}/patch, then GET the board to verify the result. These calls require databoard:patch or databoard:write. Saving the board does not itself deploy a site.
Concurrency limit
The HTTP patch interface does not currently enforce a preflight token or an atomic board revision. A dry-run is not a reservation. Re-read before applying, avoid concurrent writers, and stop if the intended source changed. A timeout requires readback before retrying.
Supported operations and missing capabilities
Use the operations and contracts returned by agent-context and validate the specific payload with dry-run. Do not assume that an operation name implies a supported field shape.
ensure_section merges by section identity but replaces supplied data_mapping paths as a complete mapping contract. Include all mappings intended to remain.
If the existing renderer cannot represent the intended result, report the missing shared capability to a maintainer. External agents must not substitute injected application code or direct filesystem edits.
See validation and publishing.