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 Status | Endpoint | Description |
---|---|---|
All Jobs | GET /api/v1/content/_import | List all import jobs |
Active | GET /api/v1/content/_import/active | List currently running jobs |
Completed | GET /api/v1/content/_import/completed | List all completed jobs (successful or failed) |
Successful | GET /api/v1/content/_import/successful | List successfully completed jobs |
Failed | GET /api/v1/content/_import/failed | List jobs that failed |
Canceled | GET /api/v1/content/_import/canceled | List jobs that were canceled |
Abandoned | GET /api/v1/content/_import/abandoned | List 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:
Parameter | Type | Description |
---|---|---|
file | File | The CSV file containing content to import |
params | JSON string | Configuration 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#
Code | Description |
---|---|
200 | Success |
400 | Bad request (validation errors) |
401 | Authentication required |
403 | Insufficient permissions |
404 | Resource not found (job ID, content type, etc.) |
500 | Server error |
#
Tips for Successful Imports#
- Always validate your CSV file before importing
- Ensure your CSV headers match the field variables in your content type
- Use the monitor endpoint for tracking long-running imports
- Check failed jobs for detailed error messages
- Be mindful of permissions - importing requires appropriate user rights