Admin Scaffold Hub From Template
Create a hub from a hubTemplate in ONE transaction (spec §5, create mode).
Returns 201 with the hub id plus the ordered per-resource summary
(created / skipped / reason), so a caller can tell what actually happened
without diffing the hub. A REPLAY (same Idempotency-Key, same request)
returns 201 with the SAME summary and replayed: true.
Error codes
405 (bare, Allow: GET) — HUB_SCAFFOLD_ENABLED is False; the
route answers exactly like a backend
without this op. Enforced by
_FlagGatedAPIRoute BEFORE body
parsing, auth and the rate limiter
(module docstring).
400 idempotency_key_invalid — Idempotency-Key missing, empty, or
over 255 characters.
409 catalog_digest_mismatch — the client’s catalog digest is stale.
404 template_not_found — hubTemplateId/pageTemplateId unknown to
the served catalog.
409 template_not_scaffoldable— the hubTemplate’s lifecycle is not
scaffold-eligible.
422 invalid_scaffold_request — a malformed template block (spaces,
onboarding, policies, playlists,
navigation), an unresolved token, an
invalid page tree, a batch-limit or
payload-size breach, or an
unresolvable welcome-post space/author.
409 hub_slug_unavailable — no unique hub slug could be minted
after HubService.create’s race
retries.
409 hub_resource_conflict — a child resource (space slug, attribute
definition slug, playlist item) was
claimed concurrently mid-op.
409 page_conflict /
reserved_page_conflict — the page matrix’s own conflicts.
409 idempotency_fingerprint_mismatch — the Idempotency-Key was reused
with a different request, or lost a
concurrent claim race.
EVERY code above is a ScaffoldError subclass RAISED out of this handler
— never returned inline — and mapped by the centrally-registered
scaffold_error_handler, which runs AFTER get_db()’s except-branch
has rolled the whole transaction back. See the module docstring.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Path Parameters
Body
Response
Successful Response