Content Import API

Overview#


The Content Import API allows you to import content from CSV files into dotCMS, monitor import jobs, and manage their lifecycle. This cheat sheet provides a quick reference for the most common operations.

Authentication#


All endpoints require proper authentication. Unauthorized requests will receive a 401 error.

Base URL#


All endpoints start with: /api/v1/content/_import

Key Operations#


Import Content#

POST /api/v1/content/_import

Import content from a CSV file:

curl -X POST \ http://your-dotcms-instance/api/v1/content/_import \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@your_data.csv" \ -F "params={\"contentType\":\"YourContentType\",\"language\":\"1\",\"workflowAction\":\"publish\"}"

Validate Content Before Import#

POST /api/v1/content/_import/_validate

Validate CSV data without importing:

curl -X POST \ http://your-dotcms-instance/api/v1/content/_import/_validate \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@your_data.csv" \ -F "params={\"contentType\":\"YourContentType\",\"language\":\"1\",\"workflowAction\":\"publish\"}"

Get Job Status#

GET /api/v1/content/_import/{jobId}

Check status of a specific import job:

curl -X GET \ http://your-dotcms-instance/api/v1/content/_import/e6d9bae8-657b-4e2f-8524-c0222db66355 \ -H "Authorization: Bearer YOUR_TOKEN"

Monitor Job Progress in Real-time#

GET /api/v1/content/_import/{jobId}/monitor

Stream real-time updates of a job's progress (SSE):

curl -X GET \ http://your-dotcms-instance/api/v1/content/_import/e6d9bae8-657b-4e2f-8524-c0222db66355/monitor \ -H "Authorization: Bearer YOUR_TOKEN"

Cancel an Import Job#

POST /api/v1/content/_import/{jobId}/cancel

Cancel a running import job:

curl -X POST \ http://your-dotcms-instance/api/v1/content/_import/e6d9bae8-657b-4e2f-8524-c0222db66355/cancel \ -H "Authorization: Bearer YOUR_TOKEN"

List Jobs by Status#


Get jobs with different statuses (all endpoints support pagination with page and pageSize parameters):

Job StatusEndpointDescription
All JobsGET /api/v1/content/_importList all import jobs
ActiveGET /api/v1/content/_import/activeList currently running jobs
CompletedGET /api/v1/content/_import/completedList all completed jobs (successful or failed)
SuccessfulGET /api/v1/content/_import/successfulList successfully completed jobs
FailedGET /api/v1/content/_import/failedList jobs that failed
CanceledGET /api/v1/content/_import/canceledList jobs that were canceled
AbandonedGET /api/v1/content/_import/abandonedList jobs that were abandoned

Example for pagination:

curl -X GET \ "http://your-dotcms-instance/api/v1/content/_import/successful?page=2&pageSize=10" \ -H "Authorization: Bearer YOUR_TOKEN"

Import Parameters#


When submitting an import or validation request, the required parameters include:

ParameterTypeDescription
fileFileThe CSV file containing content to import
paramsJSON stringConfiguration for the import process

The params JSON object should include:

{ "contentType": "YourContentType", // Required: The content type to import into "language": "1", // Required: The language ID "workflowAction": "publish" // Required: Workflow action (e.g., publish, save) }

Response Codes#


CodeDescription
200Success
400Bad request (validation errors)
401Authentication required
403Insufficient permissions
404Resource not found (job ID, content type, etc.)
500Server error

#


Tips for Successful Imports#


  1. Always validate your CSV file before importing
  2. Ensure your CSV headers match the field variables in your content type
  3. Use the monitor endpoint for tracking long-running imports
  4. Check failed jobs for detailed error messages
  5. Be mindful of permissions - importing requires appropriate user rights