[API] Import new Project

Creates a new project by importing content from multiple supported formats.

POST projects/?action=import&format={formatType}

Authentication

This request requires basic authentication.

Request Parameters

Query params

action	string	Action to perform. Only import is supported.
format	string	Specifies how the import data is provided. Can be url or base64.

Body params

importFormat	string	Import format. Supported values: Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx, AutoDocs.
inputFileContent	string	[optional] Base64-encoded content of the file to import. Required if base64 is selected for the format query parameter. If url format is selected, this parameter is ignored.
inputFileName	string	[optional] The name of the file with an extension. Required if base64 is selected for the format query parameter. If url format is selected, this parameter is ignored.
inputFileUrl	string	[optional] The URL of the file. It can be a public URL (no authentication required) or a path to a file in ClickHelp Storage. Required if url is selected for the format query parameter. If base64 format is selected, this parameter is ignored.
newProjectId	string	[optional] The ID of a new project where to import a definition. Either newProjectId or newProjectName should be specified.
newProjectName	string	[optional] The name of a new project where to import a definition. Either newProjectId or newProjectName should be specified.
newProjectLanguageFourLetterCode	string	[optional] An ISO 639 four-letter language code of a new project where to import a definition. If not specified, the en-US code is used.
options	object	Additional import parameters.
__type	string	The type of the import options. Allowed types for the formats: For the AutoDocs format, AutoDocsImportOptions is allowed. For the Word format, WordImportOptions is allowed. For the Rtf format, RtfImportOptions is allowed. For the Epub format, EpubImportOptions is allowed. For the Odt format, OdtImportOptions is allowed. For the Html format, HtmlImportOptions is allowed. For the Markdown format, MarkdownImportOptions is allowed. For the ProjectBackup format, ProjectBackupImportOptions is allowed. For the Docfx format, DocfxBackupImportOptions is allowed.
isDownloadExternalLinkedFiles	bool	[optional] Whether or not to download files linked from your content. Set to False by default. Available for these formats: Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx.
isDownloadExternalLinkedImages	bool	[optional] Whether or not to download images linked from your content. Set to True by default. Available for these formats: Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx.
tocGenerationType	string	[optional] Defines how the imported document will be split into topics. Acceptable values for Word, Rtf, Epub, Odtformats: UseStyleOutline, UseParagraphOutline, UseTcFields, ImportAsSingleTopic. Set to UseStyleOutline by default. Acceptable values for Htmland Markdown formats: UseParagraphOutline and ImportAsSingleTopic. Set to ImportAsSingleTopic by default.
maxTocOutlineLevel	string	[optional] The maximum TOC depth for the imported file. Set to 2 by default. Available for these formats: Word, Rtf, Epub, Odt.
stylesProcessingType	string	[optional] Configuration of how ClickHelp should handle the styles. Acceptable values: KeepPreciseStyles , OptimizeStyles , DoNotImportStyles. Set to OptimizeStyles by default. Available for these formats: Word, Rtf, Epub, Odt, Html, Markdown.
imageFormat	string	[optional] The desired format for image files: Png or Jpeg. Set to Png by default. Available for these formats: Word, Rtf, Epub, Odt.
splitModeType	string	[optional] Import mode for the AutoDocs format: GroupMethods, SeparateTopics or SingleTopic.

Samples

Request samples

AutoDocs

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "AutoDocs",
    "inputFileUrl": "https://petstore.swagger.io/v2/swagger.json",
    "newProjectName": "OpenAPI via API",
    "newProjectId": "openapi-project",
    "newProjectLanguageFourLetterCode": "en-US",
    "options": {
        "__type": "AutoDocsImportOptions",
        "splitModeType": "SeparateTopics"
    }
}'

Word

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Word",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.docx",
    "newProjectName": "User Guide", 
    "newProjectLanguageFourLetterCode": "en-US",
    "options": {
        "__type": "WordImportOptions",
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true, 
        "tocGenerationType": "UseStyleOutline",
        "maxTocOutlineLevel": 2,
        "stylesProcessingType": "OptimizeStyles", 
        "imageFormat": "Png" 
  }
}'

Rtf

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Rtf",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.rtf", 
    "newProjectName": "RTF Manual",
    "newProjectLanguageFourLetterCode": "en-US",
    "options": {
        "__type": "RtfImportOptions", 
        "isDownloadExternalLinkedFiles": false,
        "isDownloadExternalLinkedImages": true,
        "tocGenerationType": "UseStyleOutline", 
        "maxTocOutlineLevel": 2, 
        "stylesProcessingType": "KeepPreciseStyles", 
        "imageFormat": "Jpeg"  
  }
}'

Epub

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Epub",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.epub",
    "newProjectId": "epub-book", 
    "newProjectLanguageFourLetterCode": "en-US",
    "options": {
        "__type": "EpubImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true, 
        "tocGenerationType": "UseStyleOutline", 
        "maxTocOutlineLevel": 3, 
        "stylesProcessingType": "DoNotImportStyles",
        "imageFormat": "Png" 
  }
}'

Odt

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Odt",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.odt", 
    "newProjectId": "odt-manual", 
    "newProjectLanguageFourLetterCode": "en-US", 
    "options": {
        "__type": "OdtImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true, 
        "tocGenerationType": "UseStyleOutline", 
        "maxTocOutlineLevel": 3, 
        "stylesProcessingType": "OptimizeStyles", 
        "imageFormat": "Png" 
  }
}'

Html

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Html",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.zip", 
    "newProjectName": "HTML Import", 
    "newProjectLanguageFourLetterCode": "en-US", 
    "options": {
        "__type": "HtmlImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true, 
        "tocGenerationType": "ImportAsSingleTopic",
        "stylesProcessingType": "OptimizeStyles"
  }
}'

Markdown

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Markdown",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.zip", 
    "newProjectName": "Markdown Docs", 
    "newProjectLanguageFourLetterCode": "en-US", 
    "options": {
        "__type": "MarkdownImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true, 
        "tocGenerationType": "ImportAsSingleTopic", 
        "stylesProcessingType": "KeepPreciseStyles"
  }
}'

ProjectBackup

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "ProjectBackup",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/project-backup.zip", 
    "newProjectName": "Restored Project", 
    "newProjectLanguageFourLetterCode": "en-US", 
    "options": {
        "__type": "ProjectBackupImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true 
  }
}'

Docfx

Copy Code

Bash (Unix Shell)

[Bash (Unix Shell)]

curl --location --request POST 'https://{portal-url}/api/v1/projects/?action=import&format=url' \
--data-raw '{
    "importFormat": "Docfx",
    "inputFileUrl": "https://myportal.clickhelp.co/resources/Storage/import-sample.zip", 
    "newProjectId": "docfx-docs", 
    "newProjectLanguageFourLetterCode": "en-US", 
    "options": {
        "__type": "DocfxBackupImportOptions", 
        "isDownloadExternalLinkedFiles": false, 
        "isDownloadExternalLinkedImages": true 
  }
}'

Response body sample

Copy Code

JSON

[JSON]

{
    "taskKey": "84623f07c1644b12add45da9df56ea9e"
}

Response fields

taskKey	The task key of the import process.