Create Page Batch

POST /api/v1/organizations/{organization_id}/projects/{project_id}/page-batches

Accepts 1–500 Page Import or Code2Des requests. Requires project Write access. Stores the batch and items in PostgreSQL and returns 202 before processing.

For discovery, use type: "page_discovery" with exactly one item. url accepts a homepage or .xml sitemap; a sitemap is parsed without fetching its listed pages. Optional fields are maxPages (1–1,000, default 500), maxDepth (0–5, default 3), includePaths, and excludePaths (up to 20 path prefixes beginning with /). Poll GET /page-batches/{batch_id}/discovery for status (0 processing, 1 completed, 2 failed), pages, path groups, warnings, truncated, and updated_at. The read endpoint requires project Read access. Selecting URLs does not import them; submit a separate page_import batch of up to 500 selected URLs.

{
  "batchId": "00000000-0000-4000-8000-000000000001",
  "type": "page_import",
  "items": [
    { "name": "Home", "url": "https://example.com/", "captureMode": "static" }
  ]
}

For generation, use type: "code2des" and items containing pageImportId, figmaFileKey, screenId, and optional stateId / placementTarget. Each variation counts as one item. Import and generation remain separate batches.

Repeating the same normalized request with the same UUID returns that batch. Different input with the same UUID returns 409. Validation of source availability and project access happens per item during dispatch; invalid items fail independently.

Codebase routes accept the same manifest fields as the single Page Import API. Upload assets directly to S3 before submitting the batch.

202 response

Returns batchId, type, createdAt, aggregate counts, and ordered items. Initially all items are queued.