Import

The import API receives the ZIP file from the ExportAPI and includes many options to add, replace, or update services in the destination environment. The API is designed not to proceed if a successful import cannot be completed.

Prerequisites to import Spark services

• Only 1 job can be executed at once per tenant.

• Any destination folders need to already exist and be accessible with the provided authorization.

• The uploaded package size does not exceed the configured limit (default to 200 MB).

Import actions for Spark services

The services_modify and services_existing parameters can be used to control the destination and overwrite behaviors.

• The services_modify service_uri_source and service_uri_destination parameters can be used to map each source service to a destination. This is useful if the folder and service names in production are different than in a lower environment.

• The services_existing parameter controls the behavior if the destination already exists.

• Where possible, the existing version_id of a service version will be migrated to the new environment (see Execute API (v3) for more information about the version_id).

Destination	services_existing parameter	Import action
Service does not currently exist	does not impact import action	A new service will be added with all of the service versions included in the source.
Service currently exists	not defined	The upload activity will fail.
Service currently exists	abort	The upload activity will fail.
Service currently exists	replace	The destination service and service versions will be replaced by the service in the source. Note that the previous API Call History for the service will no longer be accessible.
Service currently exists	add_version	The destination service will be updated with the service versions included from the source. The semantic versioning will follow the parameter provided in update_version_type.

Authorization

• Bearer {token} accessible from Authorization - Bearer token or systematically via Client Credentials.

  • The request headers should include a key for Authorization with the value Bearer {token}.

• API key created from Authorization - API keys. The API key groups must contain User groups that are also assigned to Permissions - Features permissions Spark.Imports.json or Spark.AllEncompassingProxy.json.

  • The request headers should include the keys x-synthetic-key and x-tenant-name with the values of the API key and tenant name respectively.

POST import job

Returns: Response from GET import status.

POST /{tenant}/api/v4/import

Path parameters

Key	Value
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.

Request body

Content-Type: multipart/form-data

Key	Value
file *	File to import from the previous step.
importRequestEntity	Stringified JSON content of the importRequestEntity parameters. If not provided, sensible defaults will be attempted for the import.

importRequestEntity parameters

Key	Value
inputs.services_modify	Array of services modify objects. If not provided, it is assumed that the destination is taken from the source folder and service name. The primary use of this parameter is to modify the destination of the exported service. Settings will apply only to the noted services. JSON Array of the imported service settings: service_uri_source in C.SPARK_XCALL() {folder}/{service} reference the service provided in the source. service_uri_destination in C.SPARK_XCALL() {folder}/{service} format to change destination folder and service. If omitted assume the same as service_uri_source. update_version_type major, minor, or patch, if not provided assume minor as default. This only applies when services_existing is add_version. Alternatively if copy is provided, then Spark will try to use the exact same semantic versions as the source. See the sample request for an example.
services_existing	Optional parameter that defines how to process the service if there is an existing service in the destination folder with the same service name exists and is accessible. The default value is abort which means the import will fail if there is already an existing service with in the specified destination folder and service. replace means the entire service will be removed and replaced with the service versions in the imported file. Note that the previous API Call History for the service will no longer be accessible. If there are existing overlapping semantic versions between the destination and source, this will maintain the existing version_id. add_version means that any existing services will be updated with the service versions included in the file.
source_system	Tag API call. Example: mycicd
correlation_id	Tag API call. Example: 456

Sample request

• The exported ZIP contains a service taken from the folder myproduct service myservice.

• The destination for this service is the folder newproduct and service newservice.

• The service version semantic versions will be incremented with a major revision number, e.g. from 1.3.1 to 2.0.0.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/import' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/C:/myfolder/myfile.zip"'
--form 'importRequestEntity="{
	\"inputs\": {
		\"services_modify\": [{
			\"service_uri_source\": \"myproduct/myservice\",
			\"service_uri_destination\": \"newproduct/newservice\",
			\"update_version_type\": \"major\",
		}]
	},
	\"services_existing\": \"add_version\",
	\"source_system\": \"mycicd\",
	\"correlation_id\": \"456\"
}"'

importRequestEntity

{
	"inputs": {
		"services_modify": [{
			"service_uri_source": "myproduct/myservice",
			"service_uri_destination": "newproduct/newservice",
			"update_version_type": "major"
		}]
	},
	"services_existing": "add_version",
	"source_system": "mycicd",
	"correlation_id": "456"
}

Response

HTTP 200 OK Content-Type: application/json

Returns the response from GET import status.

GET import status

Returns: status response.

GET /{tenant}/api/v4/import/{jobId}/status

Path parameters

Key	Value
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.
jobId *	id from POST import job.

Response

Similar to the Export API Request body, with the following differences:

Key	Value
outputs.services	Array of the imported services sorted by folder_source, service_source: service_uri_source in C.SPARK_XCALL() format of {folder}/{service} folder_source service_source service_id_source service_uri_destination in C.SPARK_XCALL() format of {folder}/{service} folder_destination service_destination service_id_destination status: added service did not exist and it was added. replaced service exists and was replaced. updated service exists and new service versions were added.
outputs.service_versions	Array of the imported service versions sorted by folder_source, service_source, version_source: service_uri_source in C.SPARK_XCALL() format of {folder}/{service}[{version}] folder_source service_source version_source (semantic version) service_id_source (not possible to get this value) version_id_source service_uri_destination in C.SPARK_XCALL() format of {folder}/{service}[{version}] folder_destination service_destination version_destination service_id_destination version_id_destination status: added service version was added. replaced service version existed and was replaced.

Sample response

HTTP 200 OK Content-Type: application/json

{
    "object": "import",
    "id": "df0e9343-5657-4fd2-959d-89dc4eadf12d",
    "response_timestamp": "2023-11-01T03:21:34.573Z",
    "status": "completed",
    "status_url": "https://excel.myenvironment.coherent.global/mytenant/v4/import/df0e9343-5657-4fd2-959d-89dc4eadf12d/status",
    "process_time": 3453,
    "outputs": {
        "services": [
            {
                "service_uri_source": "myproduct/myservice",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "service_uri_destination": "newproduct/newservice",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "service_id_destination": "5d14d6a4-392c-4c51-be4b-6d2b98e162fe",
                "status": "replaced"
            }
        ],
        "service_versions": [
            {
                "service_uri_source": "myproduct/myservice[1.0.0]",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "version_source": "1.0.0",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "version_id_source": "4b05a3ea-92fa-4168-8bcd-5f732a5adc5d",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "version_destination": "1.0.0",
                "service_uri_destination": "/newproduct/newservice[1.0.0]",
                "service_id_destination": "6bd0337c-186b-4813-a4ac-49d565d86fdb",
                "version_id_destination": "6c73f2e4-b354-4695-a991-c52817a5f25f",
                "status": "replaced"
            },
            {
                "service_uri_source": "myproduct/myservice[1.1.0]",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "version_source": "1.1.0",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "version_id_source": "e0901e15-b305-4d43-b037-3d39cf017260",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "version_destination": "1.1.0",
                "service_uri_destination": "/newproduct/newservice[1.1.0]",
                "service_id_destination": "6bd0337c-186b-4813-a4ac-49d565d86fdb",
                "version_id_destination": "280341de-04d4-482c-ad4c-b8c03fffa517",
                "status": "added"
            }
        ]
    },
    "source_system": "mycicd",
    "correlation_id": "456"
}

PATCH import

Change import job status. This can cancel an errant job.

Returns: Response from GET import status.

PATCH /{tenant}/api/v4/import/{jobId}

Path parameters

Key	Value
environment *	Environment is part of your Log in to Spark URL.
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.
jobId *	id from POST import job.

Request

Content-Type: application/json

{"import_status":"cancelled"}

Response

HTTP 200 OK Content-Type: application/json

Returns the response from GET import status.

GET import status across the tenant

Get information about import jobs that are in_progress_imports or recent_imports within the past 1 h.

Returns: Import jobs.

• If you are a supervisor:pf user, you will be able to see all imports run by users within your tenant.

• Otherwise, you will only see information about the batches that were initiated by yourself.

GET /{tenant}/api/v4/import/status

Path parameters

Key	Value
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.

Sample response

HTTP 200 OK Content-Type: application/json

{
    "in_progress_imports": [
        {
            "object": "import",
            "id": "8ecadd1b-371f-4c23-b8cb-e7eba2f26acf",
            "data": {
                "import_status": "in_progress",
                "response_timestamp": "2025-08-14T10:16:39.717Z",
                "created_by": "[email protected]",
                "created_timestamp": "2025-08-14T10:16:33.082Z",
                "updated_timestamp": "2025-08-14T10:16:33.305Z",
                "process_time": 0
            }
        }
    ],
    "recent_imports": [],
    "tenant": {
        "configuration": {
            "import_api_job_limit": 1
        },
        "status": {
            "import_api_jobs_in_progress": 1
        }
    }
}