> 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
Reusable slide decks built from uploaded image assets, with draft and published states.
Build a draft from asset URLs
POST /api/v1/carousels accepts title and slides. Normalized slides need asset_url, image_url or image values. Upload images through the shared asset endpoint first and use its returned URL. Keep status=draft during review.
Create without an ID or slug. An explicit unavailable target returns 404. Read the revision from GET and send expected_revision on every update. PATCH preserves omitted fields; POST/PUT replacement applies defaults for omitted fields. Missing revision returns 428, and a changed revision returns 409.
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/carousels" \
-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/carousels
Intended request methods: GET, POST, PUT, PATCH. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: carousel:read, carousel:write, databoard:read, databoard:write
Observed JSON fields: blog_url, cover_image, description, id, slides, slug, status, title, topic, youtube_url.
Selected rejection messages:
- JSON body required
- title is required
- slides must contain asset_url/image_url/image values
- Could not save carousel deck
/api/v1/carousels/{idOrSlug}
Intended request methods: GET, POST, PUT, PATCH. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: carousel:read, carousel:write, databoard:read, databoard:write
Observed JSON fields: blog_url, cover_image, description, id, slides, slug, status, title, topic, youtube_url.
Selected rejection messages:
- Carousel deck not found
- JSON body required
- title is required
- slides must contain asset_url/image_url/image values
- Could not save carousel deck
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.
Hardened target handling
Create through POST /api/v1/carousels without an ID or slug. An explicit ID/slug is an update lookup: if it is missing or not owned, the API returns 404 and does not create a replacement. Collection PUT/PATCH without a target returns 400. Updates now require expected_revision. PATCH preserves omitted fields; POST/PUT replacement can default omitted fields. See the external-agent write contract below.
Use GET /api/v1/help?view=operations&resource=carousels for allowed methods. A successful transport check is not proof of ownership or valid field values.
External-agent write contract
Use GET /api/v1/help?view=guide&resource=carousels for this workflow over HTTP, and GET /api/v1/help?view=schema&resource=carousels for the supported fields. No repository access is needed.
POST /api/v1/validate accepts resource=carousels, operation=create/replace/patch and data containing the proposed payload. It checks fields without saving the carousel. It does not check target ownership, revision freshness, image access, or publishing. A key with carousel:write or the existing databoard:write alternative is required.
Creates require a nonempty title. Send only documented fields; unknown keys, wrong types, unsupported status values and malformed slides return 422 with field paths. Booleans and numeric values are not silently converted to text. Slide arrays are limited to 100 entries.
GET a carousel and read its revision. Every update must send that value as expected_revision. Missing revision returns 428; stale revision returns 409. The update compares the persisted MongoDB snapshot atomically, including changes made within the same timestamp second.
PATCH preserves omitted fields. POST or PUT to an existing target performs replacement using the save defaults, so include the full desired fields. An explicit ID or slug cannot create a record. No versioned Carousel delete API is implemented.
{
"resource": "carousels",
"operation": "create",
"data": {
"title": "Draft carousel",
"status": "draft",
"slides": []
}
}After validation, send the data object itself to POST /api/v1/carousels. Record the returned ID; then GET /api/v1/carousels/{id}. Never retry a timed-out create blindly: idempotent create receipts are not implemented yet.
HTTP discovery and safety contract
Read GET /api/v1/help?view=guide&resource=carousels 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.