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):

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:

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#

---

#

---

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