Bulk + Export/Import API

Sweep-actions across many Stories, plus full Space backup/restore.

Bulk story actions

POST /v1/spaces/{slug}/stories/bulk

Body:

{
  "action": "publish",
  "uuids": ["abc-...", "def-...", "..."],
  "options": { "publish_at": "2026-06-01T08:00:00Z" }
}

Supported action values:

action	options	Effect
publish	publish_at?	Publish each story; with publish_at schedules instead of immediate
unpublish	—	Flip status to draft
archive	—	Soft-delete (recoverable via restore)
restore	—	Undo archive
transition	to_stage (required)	Workflow transition (RBAC + approval rules still apply)
delete	confirm: "yes-permanently"	Hard delete; requires admin role

Response: 200 { processed, failed: [{ uuid, error }] }. Partial failures are recorded — the rest still process.

Export

GET /v1/spaces/{slug}/export

Streams a .tar.gz containing:

• stories.ndjson — one Story per line, all versions
• blueprints.ndjson — component blueprints
• locales.ndjson — Locale rows
• audience-segments.ndjson — segments + rules
• assets/ — original files (only when ?with_assets=1)
• manifest.json — schema version + counts

Auth: auth:sanctum + space.scope middleware. Rate-limited throttle:5,60 (5 per hour) — the operation is expensive.

Import

POST /v1/spaces/{slug}/import
Content-Type: multipart/form-data

Field: bundle (the .tar.gz from export).

Modes (query param ?mode=):

mode	Behaviour
dry-run (default)	Validate, return diff, write nothing
merge	Insert new, update existing (matched by UUID)
replace	Wipe target Space first, then import — destructive

Response includes a per-entity counts dict plus any UUID conflicts.

replace mode

replace deletes everything in the target Space (stories, blueprints, locales, segments) before import. Confirm twice in the admin SPA before clicking the button. CLI: peacock import bundle.tgz --mode replace --i-have-a-backup.

See also

• /api/stories — single-story CRUD
• /api/workflow — bulk transition rules
• /guide/self-host — Space-level backup with pg_dump