Meet the Import REST API: Migrate Content at Scale—Safely, Visibly, and Fast

Getting content into a CMS shouldn’t feel like rolling a boulder uphill. Our new Import REST API removes the friction with validation-before-import, performance toggles, real-time monitoring, and clear error reporting—so migrations are faster, safer, and a lot less mysterious.

Why we built it

Large content imports can be fragile, opaque, and hard to troubleshoot—especially during first-time migrations. Teams lack pre-flight validation, real-time progress, and actionable error messages that are key to stress free imports of large data sets. We set out to create a tool that makes migration delightful by making it easy to validate, monitor, and diagnose issues during large or complex content migrations.

What we delivered: a set of REST endpoints that let you validate before import, monitor progress, tune commit/savepoint behavior (including fail-fast), and surface detailed, standardized error codes—all running on a job queue for scale and reliability.

Who benefits: developers and DevOps who run migrations now get fine-grained control and better signals; content owners who get clearer feedback on what to fix, which shortens the path to go-live.

Availability, pricing & current limits

• Cost: included—no extra SKU

• First fully available: version 25.08.25; usable (but not fully stable) in 25.7.10 LTS

• Format: only CSV file format is supported at this time

• Known limitations: Content History (versions) not supported at this time

What you can do with the Import REST API

• Import large datasets via CSV, including multilingual content, with workflow integration

• Orchestrate imports with a job queue; query status and stream progress via SSE

• Validate first (dry run) to catch problems before writing anything

• Control behavior on errors (fail fast vs. continue and report)

• Handle content relationships and updates to existing items

Quick start: a simple “Articles” import (dry run → import → monitor)

We’ll assume you have a CSV file articles.csv with headers that match your content type’s field variables. Authentication uses a bearer token for a user in your system with the proper permissions to create and publish content.

Base path: /api/v1/content/_import

1) Dry run (validate without writing)

curl -X POST \
  "https://your-dotcms/api/v1/content/_import/_validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@articles.csv" \
  -F 'form={"contentType":"Article","language":"1","workflowActionId":"yourPublishWorkflowActionID"}'

• Replace the URL with the URL of your instance

• Replace "YOUR_TOKEN" with the API token for the user you are using in your instance

• Replace "articles.csv" with the full path of the CSV file on your local drive

• Replace "yourPublishWorkflowActionID" with the ID of the Publish Workflow (you can get this from the Workflows tool by clicking into the workflow you are using for the content_type, then selecting the workflow action you want to send the content through, then selecting the ActionID at the top left of the screen for the workflow action)

This performs schema/field checks and returns validation feedback without persisting data.

2) Start the import job

curl -X POST \
  "https://your-dotcms/api/v1/content/_import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@articles.csv" \
  -F 'form={"contentType":"Article","language":"1","workflowActionId":"yourPublishWorkflowActionID"}'

Response includes a jobId you’ll use to monitor and query status.

3) Monitor progress in real time (SSE)

curl -N -X GET \
  "https://your-dotcms/api/v1/content/_import/<jobId>/monitor" \
  -H "Authorization: Bearer YOUR_TOKEN"

This streams progress updates until completion. Use it for long-running jobs. You can get the jobID from the response after initiating the import.

4) Check job status on demand (polling)

curl -X GET \
  "https://your-dotcms/api/v1/content/_import/<jobId>" \
  -H "Authorization: Bearer YOUR_TOKEN"

Handy for dashboards or CI scripts that poll instead of streaming.

5) List jobs by state (for history & audits)

# Examples
curl -X GET "https://your-dotcms/api/v1/content/_import/successful?page=1&pageSize=25" -H "Authorization: Bearer YOUR_TOKEN"
curl -X GET "https://your-dotcms/api/v1/content/_import/failed" -H "Authorization: Bearer YOUR_TOKEN"

You can list all, active, completed, successful, failed, canceled, or abandoned jobs, with pagination.

6) Cancel if needed

curl -X POST \
  "https://your-dotcms/api/v1/content/_import/<jobId>/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN"

If something’s off, stop the job cleanly and review errors.

Pro tips: Always validate first; match CSV headers to field variables; monitor long jobs; review failed jobs for detailed messages; confirm permissions.

Dial it in: the main controls (and why they matter)

• contentType / language / workflowAction — direct content into the right type and locale, and apply the correct workflow step (e.g., publish vs. save). Keeps imports aligned with governance from day one.

• Batch commit (commit interval) — write to the database every n records to balance throughput vs. transaction safety. Recommended around 500+, depending on volume.

• Savepoints (fine-grained rollback) — on error, only the failing batch rolls back; previously imported items remain. This turns a “start over” day into a “fix and continue” hour.

• Fail-fast vs. continue-on-error — stop at first error for strict pipelines, or keep going and produce a comprehensive error report for cleanup.

• Relationships — import with relationships intact; choose to replace, remove, or preserve existing links.

• Multilingual — import multiple languages in one operation for globally managed content.

• Updates vs. creates — update existing items by identifier/key to avoid duplicates during iterative loads.

• Binary fields — supported; in this phase, ensure binaries are uploaded and referenced in the CSV (path/id).

Best-fit use cases

• Big, cross-type migrations where you need monitoring and commit/savepoint tuning

• Complex data models with related content that must be preserved

• Developer-led imports from external systems as part of initial onboarding

• Automated CI/CD flows that regularly push content programmatically

Conclusion

Migrations shouldn’t be frustrating. With pre-flight validation, real-time visibility, robust rollback, and clear errors—the Import REST API turns bulk imports into a predictable, repeatable part of your delivery pipeline. Start with a dry run, dial in your controls, and ship content with confidence.