Requires Bearer auth. Imports default to draft unless ?publish=true.
| Action | Method | Path |
|---|---|---|
| Create guide | POST | /api/gdf/v1/guides?ai_readable=1 |
| Scaffold outline | POST | /api/gdf/v1/guides/scaffold or …/{slug}/scaffold |
| Replace guide | POST | /api/gdf/v1/guides/{slug}/import |
| Patch one item | PATCH | /api/gdf/v1/guides/{slug}/items/{item_id} |
| Append item | POST | /api/gdf/v1/guides/{slug}/items |
| Delete item | DELETE | /api/gdf/v1/guides/{slug}/items/{item_id} |
| Reorder items | POST | /api/gdf/v1/guides/{slug}/reorder |
Reorder body: { "item_ids": ["item-1", "item-2", …] } (complete list) or { "move": { "item_id": "item-3", "after_item_id": "item-1" } }.
Prefer PATCH one item over replacing an entire guide. Prefer scaffold over dozens of appends.
Agents may add namespaced metadata.ai.* fields (tags, keywords, external refs) on patch; humans need not see them in the reader.