---
updatedAt: 2026-09-09T09:34:03.000Z
agentTools:
siteIndex: https://documentation.bloomreach.com/llms.txt
projectIndex: https://documentation.bloomreach.com/content/llms.txt
---
# Create content (documents and pages) in a specific project.
Create content (documents and pages) in a specific project.
### Automatic creation of folders
Both document and page endpoints require a path provided in the URL. The path corresponds to a folder structure in the content tree which if not existing already, it will be created. The created folders are the simplest folders you can create in CMS, meaning no "allowed content" is configured, neither translation links, nor any particular sorting.
### Document linking
Documents and pages may contain links to other documents that do not exist yet, or exist as a part of the same import payload. They can even reference each other. To support this, the batch import operation is split into two steps:
- Content Import: during this step, documents containing references to non existing links are being saved with a placeholder UUID rather than a real link (which does not exist yet).
- Linking: update all existing document references with a reference, otherwise report an error. Invalid link references remain, so the developers have a choice of either manually fixing the links through CMS, fix the payload and rerun the import operation, or drop the whole branch and start over again.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "Content Batch Import API",
"description": "The Content Batch Import API enables developers to import large amounts of content into a Bloomreach project.\n\nAll operations are performed within the context of a developer project, and all writes are performed on the unpublished variant of a page or document associated with the project. This also provides an important benefit of being able to reject a batch as a whole in a single operation by deleting the corresponding project before merging.\n\n### How it works\n\nThe batch import works by sending a [JSON lines file](https://jsonlines.org/). The response to a batch operation is a job identifier which the caller can use to poll for the operation status.\n- When the operation is complete, the caller can obtain a report of the operation containing all successful and failed items.\n- In case of failed items, the API takes care to clean up as much as possible (e.g. delete or revert unfinished/corrupted documents) but it is also possible to easily clean up via the Projects perspective in Content SaaS UI.\n\n### Advantages\nAdvantages of using the Batch Import:\n- It takes care of references between documents, that otherwise the client needs to cater for (import documents in proper order)\n- It allows them to focus on the export from the legacy system, and using one file instead of many makes the process much easier\n- It is much more performing: it dramatically removes the overhead of making separate API requests (per document)",
"version": "Beta"
},
"externalDocs": {
"description": "See official Bloomreach documentation",
"url": "https://documentation.bloomreach.com/content/reference/content-type-management-api"
},
"servers": [
{
"url": "https://developers.bloomreach.io/management/content-import/v1"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Content Import Batch Operations",
"externalDocs": {
"description": "See",
"url": "https://documentation.bloomreach.com/content/reference/content-type-management-api"
}
}
],
"paths": {
"/project/{project_id}": {
"post": {
"tags": [
"Content Import Batch Operations"
],
"summary": "Create content (documents and pages) in a specific project.",
"description": "Create content (documents and pages) in a specific project.\n### Automatic creation of folders\nBoth document and page endpoints require a path provided in the URL. The path corresponds to a folder structure in the content tree which if not existing already, it will be created. The created folders are the simplest folders you can create in CMS, meaning no \"allowed content\" is configured, neither translation links, nor any particular sorting.\n### Document linking\nDocuments and pages may contain links to other documents that do not exist yet, or exist as a part of the same import payload. They can even reference each other. To support this, the batch import operation is split into two steps:\n- Content Import: during this step, documents containing references to non existing links are being saved with a placeholder UUID rather than a real link (which does not exist yet).\n- Linking: update all existing document references with a reference, otherwise report an error. Invalid link references remain, so the developers have a choice of either manually fixing the links through CMS, fix the payload and rerun the import operation, or drop the whole branch and start over again.",
"operationId": "importFile_1",
"parameters": [
{
"name": "project_id",
"in": "path",
"description": "specifies the project content is added to",
"required": true,
"schema": {
"type": "string"
},
"example": "vIUy9"
}
],
"requestBody": {
"description": "The payload for this operation is a json lines file that conforms to the [json lines specification](https://jsonlines.org/), and the contents are a mix of BatchDocument, BatchPage, BatchResourceBundle, BatchFolder and XPageBatchFolder entities, see [schema](https://documentation.bloomreach.com/content/openapi/62cf0c7d7db203003de12ac0)",
"content": {
"multipart/form-data": {
"schema": {
"type": "string",
"format": "binary"
},
"examples": {
"Example with 2 documents and 1 page": {
"description": "This example shows the payload for 2 documents and 1 page",
"value": "{\"type\":\"document\",\"contentType\":\"brxsaas:banner\",\"fields\":[{\"name\":\"title\",\"value\":[\"Our team is ready for your next product\"]},{\"name\":\"content\",\"value\":[\"example content
\"]},{\"name\":\"image\",\"value\":[\"\\/\"]},{\"name\":\"cta\",\"value\":[\"Start your next project\"]},{\"name\":\"link\",\"value\":[\"\\/content\\/documents\\/brxsaas\\/pages\\/products\\/all\"]}],\"name\":\"next-project11\",\"displayName\":\"Next Project11\",\"path\":\"\\/content\\/documents\\/brxsaas\\/banners\\/next-project11\"}\n{\"type\":\"document\",\"contentType\":\"brxsaas:banner\",\"fields\":[{\"name\":\"title\",\"value\":[\"Brand 1\"]},{\"name\":\"content\",\"value\":[\"Sample content
\"]},{\"name\":\"image\",\"value\":[\"\\/content\\/gallery\\/brxsaas\\/banners\\/brand-1.jpg\"]},{\"name\":\"cta\",\"value\":[]},{\"name\":\"link\",\"value\":[\"\\/content\\/documents\\/brxsaas\\/pages\\/products\\/all\"]}],\"name\":\"brand-111\",\"displayName\":\"Brand 111\",\"path\":\"\\/content\\/documents\\/brxsaas\\/banners\\/brand-111\"}\n{\"type\":\"page\", \"relativePath\":\"pages/home\", \"channelId\":\"brxsaas\",\"name\":\"home\",\"displayName\":\"Home\",\"layout\":\"two-column\",\"document\":{\"contentType\":\"brxsaas:content\",\"fields\":[{\"name\":\"title\",\"value\":[\"My page\"]},{\"name\":\"introduction\",\"value\":[\"Sample introduction\"]},{\"name\":\"content\",\"value\":[\"Example page content\"]},{\"name\":\"image\",\"value\":[\"\\/\"]},{\"name\":\"date\",\"value\":[]}]},\"containers\":[{\"path\":\"top\",\"components\":[{\"componentDefinition\":\"sample\\/single-banner-carousel\",\"componentConfigurations\":[{\"id\":\"DEFAULT\",\"content\":null,\"parameters\":[{\"name\":\"alignment\",\"value\":\"center\"},{\"name\":\"document1\",\"value\":\"banners\\/safe-workspace-1\"},{\"name\":\"document2\",\"value\":\"banners\\/safe-workspace-2\"},{\"name\":\"interval\",\"value\":\"10000\"}]}]}]},{\"path\":\"main\",\"components\":[{\"componentDefinition\":\"sample\\/titleandtext\",\"componentConfigurations\":[{\"id\":\"DEFAULT\",\"content\":{\"contentType\":\"titleandtext\",\"fields\":[{\"name\":\"title\",\"value\":[\"Welcome to brX ContentX\"]},{\"name\":\"text\",\"value\":[\"Welcome to the Bloomreach Sample Front-end Application for the brX Content.\"]}]},\"parameters\":[{\"name\":\"titlesize\",\"value\":\"H3\"},{\"name\":\"textalignment\",\"value\":\"left\"},{\"name\":\"style\",\"value\":\"style1\"}]}]},{\"componentDefinition\":\"sample\\/titleandtext\",\"componentConfigurations\":[{\"id\":\"DEFAULT\",\"content\":{\"contentType\":\"titleandtext\",\"fields\":[{\"name\":\"title\",\"value\":[\"\"]},{\"name\":\"text\",\"value\":[\"We have tried to keep it as clean, effective and simple as possible\"]}]},\"parameters\":[{\"name\":\"titlesize\",\"value\":\"H3\"},{\"name\":\"textalignment\",\"value\":\"left\"},{\"name\":\"style\",\"value\":\"style1\"}]}]},{\"componentDefinition\":\"sample\\/category-highlight\",\"componentConfigurations\":[{\"id\":\"DEFAULT\",\"content\":{\"contentType\":\"CategoryHighlight\",\"fields\":[{\"name\":\"title\",\"value\":[\"Highlight categories\"]},{\"name\":\"connectorid\",\"value\":[\"brsm\"]},{\"name\":\"CommerceCategoryCompound\",\"value\":[{\"fields\":{\"categoryid\":[\"PNB160400000000\"]}},{\"fields\":{\"categoryid\":[\"PNB160402010000\"]}},{\"fields\":{\"categoryid\":[\"PNB160401010000\"]}},{\"fields\":{\"categoryid\":[\"PNB250800000000\"]}}]}]},\"parameters\":[]}]}]}]}"
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OperationStatus"
},
"examples": {
"Example response after import": {
"description": "In this example the response can be seen after an import request is successfully submitted",
"value": {
"operationId": "0f68c6d9-cfee-49ac-9cff-6d82d34ee704",
"projectId": "vI8Xo",
"status": "STARTING",
"readCount": 0,
"writeCount": 0,
"skipCount": 0,
"startTime": null,
"endTime": null,
"errorLog": []
}
}
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
}
},
"components": {
"schemas": {
"ErrorLog": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"error": {
"type": "string"
}
},
"description": "A log of errors of an operation"
},
"OperationStatus": {
"required": [
"endTime",
"errorLog",
"exitMessage",
"operationId",
"projectId",
"readCount",
"skipCount",
"startTime",
"status",
"writeCount"
],
"type": "object",
"properties": {
"operationId": {
"type": "string",
"description": "Operation ID"
},
"projectId": {
"type": "string",
"description": "Project ID"
},
"status": {
"type": "string",
"description": "Operation Status",
"enum": [
"COMPLETED",
"STARTING",
"STARTED",
"STOPPING",
"STOPPED",
"FAILED",
"ABANDONED"
]
},
"exitMessage": {
"type": "string",
"description": "Exit Message in case of operation failure"
},
"readCount": {
"type": "integer",
"description": "Number of records in input payload",
"format": "int32"
},
"writeCount": {
"type": "integer",
"description": "Written items",
"format": "int32"
},
"skipCount": {
"type": "integer",
"description": "Skipped items",
"format": "int32"
},
"startTime": {
"type": "string",
"description": "Operation start time",
"format": "date-time"
},
"endTime": {
"type": "string",
"description": "Operation end time",
"format": "date-time"
},
"errorLog": {
"type": "array",
"description": "Operation start time",
"items": {
"$ref": "#/components/schemas/ErrorLog"
}
}
},
"description": "An entity containing information about an operation"
}
},
"securitySchemes": {
"bearerAuth": {
"type": "apiKey",
"name": "x-auth-token",
"in": "header"
}
}
}
}
```