Using the export/import API

Overview

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

How does it work?

Two API endpoints exist:

• POST /app/export - request an export (schedules an asynchronous export job). You get back a job UUID and a log filename. The service creates a ZIP archive in the Neo4j Archive folder containing the exported GraphML files.

• POST /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).

Both endpoints are asynchronous: they enqueue a job and return immediately. Use the returned UUID/log file to check progress or inspect logs.

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/app/<endpoint>

Where is the Neo4j archive folder?

The Neo4j archive folder is used:

• to store exported application .zip files (export endpoint)
• to fetch the application .zip files (import endpoint)

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

How do I export an application (enqueue export)?

• Endpoint: POST /app/export
• Content-Type: application/json
• Mandatory header: x-api-key:

Required fields (body JSON):

• database (string) - the target Neo4j database name
• export_app (string) - the application name to export

Optional fields:

• batch_size (int) - Batch size to process neo4j queries. Can be adjusted downwards for very large applications and according to the host machine’s available RAM. Defaults to 1000 if omitted or zero.

Example request:

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

Success response (HTTP 200):

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

Common failures:

• 400 / invalid request - JSON malformed or missing database / export_app fields.
• Error if the domain or application does not exist - inspect the payload and target database.
• Error if the job could not be queued - retry or contact an administrator.

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

• Endpoint: POST /app/import
• Content-Type: application/json
• Mandatory header: x-api-key: <your-api-key>

Required fields (body JSON):

• import_app (string) - the ZIP filename to import (including .zip), which must already exist in the Neo4j archive folder
• database (string) - the Neo4j database to import into

Optional fields:

• batch_size (int) - Batch size to process neo4j queries. Can be adjusted downwards for very large applications and according to the host machine’s available RAM. Defaults to 1000 if omitted or zero.

Example request:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"import_app":"MyApp-20251001-143012.zip","database":"testdb","batch_size":1000}' \
  http://<hostname>:<port>/imaging/etl/api/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. Upload the ZIP via whatever upload mechanism your installation provides, or ask an administrator to place it in the archive folder.
• 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.