Import

The import API receives the ZIP file from the Export API 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 one job can be run at a time 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 from those 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 import will fail.
Service currently exists	abort	The import 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. It 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

POST /{tenant}/api/v4/import

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in 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 CS.SPARK_XCALL() {folder}/{service} reference the service provided in the source. service_uri_destination in CS.SPARK_XCALL() {folder}/{service} format to change destination folder and service. If omitted assume the same value as service_uri_source. update_version_type major, minor, or patch. If omitted, 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 versionsas 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 and is accessible. The default value is abort which fails the import if a service already exists in the 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 and response

• 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.

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"
}

Sample request

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\"
}"'

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"
}

GET import status

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

Path parameters

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

Response

Content-Type: application/json

Key	Value
object	import
id	id for the job.
response_timestamp	Response timestamp.
status	created Job registered on Spark. in_progress Job in progress. closed Job completed successfully. closed_by_timeout Job was unable to complete within 15 min. failed Job was not able to complete.
status_url	Link to the GET status API.
process_time	Time taken for the job.
outputs.files	Array of the output files: file Link to the package. Filename of the exported object is package.zip. This can be overridden with the file_name parameter. file_hash SHA-256 of the packaged file.
outputs.services	Array of the imported services sorted by folder_source, service_source: service_uri_source in CS.SPARK_XCALL() format of {folder}/{service} folder_source service_source service_id_source service_uri_destination in CS.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 CS.SPARK_XCALL() format of {folder}/{service}[{version}] folder_source service_source version_source (semantic version) service_id_source version_id_source service_uri_destination in CS.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.
source_system	Value from POST import job.
correlation_id	Value from POST import job.

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/import/df0e9343-5657-4fd2-959d-89dc4eadf12d/status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Bearer Token}}'

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 status to cancel job

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

Path parameters

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

Request body

Content-Type: application/json

Request body	Description
{ "import_status": "canceled" }	Include this line in the JSON body to cancel the import at any time.

Sample request and response

Sample request

curl --location --request PATCH 'https://excel.myenvironment.coherent.global/mytenant/api/v4/import/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Bearer Token}}' \
--data '{
    "import_status": "canceled"
}'

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"
}

GET import jobs across the tenant

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

• 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.

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.

Sample request and response

Sample request

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/import/status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Bearer Token}}'

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": "[e-mail]",
                "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
        }
    }
}