Using the export/import API

Overview

This section describes how to export application data from one CAST Imaging instance and import it into another using the dedicated export/import API.

How does it work?

Three API endpoints exist. In each case, the target domain is specified as a path parameter in the URL:

• POST /imaging/etl/api/domains/{domainName}/app/export - request an export (schedules an asynchronous export job). You get back a job UUID, a log filename and the path to the generated ZIP archive. The service creates a ZIP archive in the Neo4j Archive folder containing the exported GraphML files.

• POST /imaging/etl/api/domains/{domainName}/app/import/upload - upload a ZIP archive to the Neo4j archive folder so that the import endpoint can reference it. Use this when you cannot place the ZIP file directly on the target server’s filesystem.

• POST /imaging/etl/api/domains/{domainName}/app/import - request an import of a previously-created ZIP (schedules an asynchronous import job). Sends the name of the ZIP file already present in the Neo4j archive folder. You get back a job UUID and log filename. The application cannot already exist in the target Neo4j database (the job will fail).

The export and import endpoints are asynchronous: they enqueue a job and return immediately. Use the returned UUID/log file to check progress or inspect logs. The upload endpoint is synchronous and returns when the file has been written to the archive folder.

Do I need to authenticate?

API export/import endpoints require authentication using a user-specific API key:

Generating an API key

• Log into the CAST Imaging UI
• Navigate to your Profile settings
• Generate your API key

Using the API key

Include your API key in the X-API-KEY header for every request:

curl -H "X-API-KEY: <your-api-key>" http://<imaging-public-url>:8090/imaging/etl/api/domains/<domainName>/app/<endpoint>

Which domain do I target?

All three endpoints require the target domain as a path parameter domainName. This value identifies the Neo4j database (“tenant”) in which the application results are stored, therefore the value you need to use depends on whether the domain/tenant mapping feature is enabled:

Where is the Neo4j archive folder?

The Neo4j archive folder is used:

• to store exported application .zip files - the export endpoint writes them here, on the instance where the export was run
• to fetch the application .zip files - the import endpoint reads them from here, on the instance where the import is run

The folder is located here:

• Microsoft Windows
• Linux via Docker

%PROGRAMDATA%\CAST\Imaging\CAST-Imaging-Viewer\Neo4jData\import\archive

/opt/cast/installation/imaging-viewer/neo4j/csv/archive

You can place .zip files in this folder directly, or send them to it using the upload endpoint.

How do I export an application (enqueue export)?

• Endpoint: POST /imaging/etl/api/domains/{domainName}/app/export
• Content-Type: application/json
• Mandatory header: x-api-key: <your-api-key>

Path parameter:

Body parameters (JSON):

Example request:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"export_app":"MyApp","batch_size":1000}' \
  http://<hostname>:<port>/imaging/etl/api/domains/testdb/app/export

Success response (HTTP 200):

{
  "success": {
    "uuid": "<job-uuid>",
    "logFile": "<log-file-name>",
    "zipPath": "<absolute-path-to-zip>"
  }
}

The export job writes the ZIP archive into the Neo4j archive folder on the instance where the export was run, and zipPath is the full path to it. There is no endpoint for downloading the archive: to import the application into another instance, you must retrieve the ZIP file from that folder yourself, then use the upload and import endpoints on the target instance. See Typical end-to-end flow.

Common failures:

• 400 / invalid request - JSON malformed or missing the export_app field.
• Error if the domain specified in the URL or the application does not exist - check the domainName path parameter and inspect the payload.
• Error if the job could not be queued - retry or contact an administrator.

How do I upload an application ZIP?

Use this endpoint to send a ZIP archive to the Neo4j archive folder on the target instance, so that it can then be referenced by the import endpoint. Use it when you cannot place the ZIP file directly on the target server’s filesystem by yourself.

• Endpoint: POST /imaging/etl/api/domains/{domainName}/app/import/upload
• Content-Type: application/octet-stream
• Mandatory header: x-api-key: <your-api-key>

Path parameter:

Query parameter:

The request body is the raw content of the ZIP file.

Example request:

curl -X POST \
  -H "Content-Type: application/octet-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-binary @MyApp-20251001-143012.zip \
  "http://<hostname>:<port>/imaging/etl/api/domains/testdb/app/import/upload?filename=MyApp-20251001-143012.zip"

Success response (HTTP 200):

{
  "success": {
    "filename": "MyApp-20251001-143012.zip"
  }
}

How do I import an application ZIP (enqueue import)?

• Endpoint: POST /imaging/etl/api/domains/{domainName}/app/import
• Content-Type: application/json
• Mandatory header: x-api-key: <your-api-key>

Path parameter:

Body parameters (JSON):

Example request:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"import_app":"MyApp-20251001-143012.zip","batch_size":1000}' \
  http://<hostname>:<port>/imaging/etl/api/domains/testdb/app/import

Success response (HTTP 200):

{
  "success": {
    "uuid": "<job-uuid>",
    "logFile": "<log-file-name>"
  }
}

Common failures and how to resolve:

• file '<name>' not found - the specified import_app ZIP is not present in the Neo4j archive folder. Send it to the archive folder using the upload endpoint, place it there directly, or ask an administrator to do so.
• Application already exists - the import is prevented if an application with the same name already exists in the target database. Either remove the existing app or import under a different name.

Typical end-to-end flow

1. Export the application on the source instance using POST /imaging/etl/api/domains/{domainName}/app/export, then note the zipPath value returned in the response. The export job writes the ZIP archive into the Neo4j archive folder on the source instance.
2. Retrieve the ZIP archive from the source instance, using the zipPath value to locate it. The API does not serve the file, therefore use whichever means you normally use to access the machine, for example a file share, scp or docker cp.
3. Upload the ZIP archive to the target instance using POST /imaging/etl/api/domains/{domainName}/app/import/upload?filename=<filename>. Skip this step if you are able to place the ZIP file in the Neo4j archive folder on the target instance directly.
4. Import the application on the target instance using POST /imaging/etl/api/domains/{domainName}/app/import, setting import_app to the filename of the ZIP file.

Migrating from an earlier version

If you are upgrading from a version earlier than 3.6.6-funcrel and you have existing integrations that call these endpoints, two changes are required:

• move the target from the database field in the request body into the URL path
• add the /domains/{domainName} segment to the endpoint URL

No other fields change.

For example, for an export where the target is testdb:

# Earlier than 3.6.6-funcrel
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"database":"testdb","export_app":"MyApp","batch_size":1000}' \
  http://<hostname>:<port>/imaging/etl/api/app/export

# 3.6.6-funcrel and above
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"export_app":"MyApp","batch_size":1000}' \
  http://<hostname>:<port>/imaging/etl/api/domains/testdb/app/export