> 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.
What this module owns
Canonical articles, publication state, group associations and channel-specific syndication variants.
Create a draft, then read it back
POST /api/v1/notes requires title, content and a writable group_id. Use status=draft while preparing content.
{
"title": "A factory workflow",
"content": "<p>A draft article for review.</p>",
"group_id": "REPLACE_WITH_WRITABLE_GROUP_ID",
"status": "draft",
"summary": "How the source becomes a generated page."
}Send the JSON file with curl --data-binary @note-draft.json and Content-Type: application/json. Read GET /api/v1/notes/{id} afterward. Verify the returned ID, group and draft state before publishing or syncing the site. Invalid or missing payload fields now return 422 with field paths; an unwritable group returns 403; an unavailable owned note returns 404.
The save handler does not require an expected revision hash. Use a fresh read and a narrow editing window; stale-write prevention needs further hardening. Editing group associations can change where the article is published. Syndication creates channel variants; it is not proof that an external channel has published them.
First read
Use API_URL with /api/v1, for example http://localhost/api/v1. Set API_KEY privately. Replace any resource placeholder with an ID returned by discovery.
curl --fail-with-body "$API_URL/notes" \
-H "Authorization: Bearer $API_KEY"Registered agent routes
The entries below are extracted from the current route and handler source. Scope tokens can represent alternatives or different method branches, not a requirement to grant every listed scope. Body fields are observed inputs, not a complete required-field schema. Follow the resource guide and the deployed validation response for a write.
/api/v1/notes
Intended request methods: GET, POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:read, notes:write
Observed JSON fields: blog_template, clear_cover, clear_cover_asset, content, cover_asset, cover_image, created_at, diarynotes_id, draft, group, group_id, group_key, html, id, media_header, note_id, notes, remove_cover, status, summary, sync_generated_site, tags, title, tittle.
Selected rejection messages:
- Group not found or not accessible
- Title is required
- Content is required
- group_id is required
- Group not found or not writable by this API key
- Note not found
- Note save failed
/api/v1/notes/{id}/groups/{group_id}
Intended request methods: POST, DELETE. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:write
Observed JSON fields: attached, selected.
Selected rejection messages:
- Note not found
- Group not found or not writable by this API key
- Note group save failed
/api/v1/notes/{id}/audio
Intended request methods: POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:write
Selected rejection messages:
- Use POST multipart/form-data
- Note not found
- Attach exactly one audio file
/api/v1/notes/{id}
Intended request methods: GET, POST, PUT, PATCH, DELETE. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:read, notes:write
Observed JSON fields: blog_template, clear_cover, clear_cover_asset, content, cover_asset, cover_image, created_at, diarynotes_id, draft, group, group_id, group_key, html, id, media_header, note_id, notes, remove_cover, status, summary, sync_generated_site, tags, title, tittle.
Selected rejection messages:
- Note not found
- Note delete failed
- Title is required
- Content is required
- group_id is required
- Group not found or not writable by this API key
- Note save failed
/api/v1/notes/{id}/syndication
Intended request methods: DELETE, GET, PATCH, POST, PUT. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:read, notes:write
Observed JSON fields: canonical_url, channel, content_html, content_text, excerpt, external_url, html, metadata, published_at, status, tags, text, title, variant.
Selected rejection messages:
- Note not found
- Syndication row not found
- Syndication delete failed
- Use GET, POST, PUT, PATCH, or DELETE
- Missing channel
- Syndication save failed
/api/v1/notes/{id}/syndication/generate
Intended request methods: POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:write
Observed JSON fields: canonical_url, channel, channels, content_html, content_text, excerpt, external_url, html, metadata, published_at, status, tags, text, title, variant.
Selected rejection messages:
- Note not found
- Missing channel
- Syndication save failed
/api/v1/notes/{id}/syndication/{sid}
Intended request methods: DELETE, GET, PATCH, POST, PUT. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: notes:read, notes:write
Observed JSON fields: canonical_url, channel, content_html, content_text, excerpt, external_url, html, metadata, published_at, status, tags, text, title, variant.
Selected rejection messages:
- Note not found
- Syndication row not found
- Syndication delete failed
- Use GET, POST, PUT, PATCH, or DELETE
- Missing channel
- Syndication save failed
Access boundary
External agents use only the versioned operations documented above and returned by the deployed catalog. Browser actions and internal controllers are not substitutes for missing API operations.
Verification before automation
Read back the owned record after a write. On a dedicated local fixture, test missing input, wrong owner, missing scope and stale revisions where supported. Confirm the request did not change state when rejected. Check the generated projection separately from the source record. Never replay sends, payments or deletion requests merely to test connectivity.
See API validation and remaining gaps for the shared test strategy.
External-agent field validation
Read GET /api/v1/help?view=guide&resource=notes and GET /api/v1/help?view=schema&resource=notes over HTTP. POST /api/v1/validate with resource=notes, operation=create/replace/patch and data containing the proposed save payload. This requires notes:write and performs payload checks only; it does not verify group access, record ownership, cover assets or delivery.
The actual save uses the same field validator. Unknown fields and incorrect types return 422. Send booleans such as sync_generated_site as JSON false/true, not strings. Use one spelling per field: title or tittle, content or html or notes, group_id or group or group_key. Canonical title/content/group_id are preferred.
Notes atomic revision checking remains unimplemented. POST/PUT/PATCH updates still share full-save semantics: title, content and group are required, and omitted tags/status may reset. A field validation pass is not safe concurrent editing. Keep one writer per note until that contract is added. Cover changes or generated-site sync can fail after the content save; read back the note before retrying.
HTTP discovery and safety contract
Read GET /api/v1/help?view=guide&resource=notes for this module's machine-readable guidance. Discover supported operations through its discovery_url when present. A null discovery_url means no direct resource API is documented; related endpoints, when provided, have their own ownership and scope requirements.
Use GET /api/v1/me with your key to confirm identity and scopes. Only request methods and fields supported by this deployment. The shared transport boundary rejects unsupported methods and malformed JSON on covered routes, but field schemas and revision checks remain resource-specific. Notes and Carousels expose typed save schemas and payload-only validation; other modules must not be assumed to share that contract.
Create, update, replace, patch, delete, send and publish are distinct capabilities. An operation absent from the returned catalog is unavailable, not permission to guess a URL. Read back after writes; after a timeout inspect the result before retrying. Never automatically replay a payment, message, deployment or deletion.