# Import

The import API receives the ZIP file from the [Export](/spark-apis/impex-apis/export.md)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 <a href="#api-request" id="api-request"></a>

* 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)](/spark-apis/execute-api/execute-api-v3.md) for more information about the `version_id`).

<table><thead><tr><th width="249.33333333333331">Destination</th><th>services_existing parameter</th><th>Import action</th></tr></thead><tbody><tr><td>Service does not currently exist</td><td>does not impact import action</td><td>A new service will be added with all of the service versions included in the source.</td></tr><tr><td>Service currently exists</td><td>not defined</td><td>The upload activity will fail.</td></tr><tr><td>Service currently exists</td><td><code>abort</code></td><td>The upload activity will fail.</td></tr><tr><td>Service currently exists</td><td><code>replace</code></td><td>The destination service and service versions will be replaced by the service in the source. <mark style="color:red;"><strong>Note that the previous</strong></mark> <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a> <mark style="color:red;"><strong>for the service will no longer be accessible.</strong></mark></td></tr><tr><td>Service currently exists</td><td><code>add_version</code></td><td>The destination service will be updated with the service versions included from the source. The semantic versioning will follow the parameter provided in <code>update_version_type</code>.</td></tr></tbody></table>

## Authorization

* `Bearer {token}` accessible from [Authorization - Bearer token](/spark-apis/authorization-bearer-token.md) or systematically via [Client Credentials](/identity-and-access-management/client-credentials.md).
  * The request headers should include a key for `Authorization` with the value `Bearer {token}`.
* API key created from [Authorization - API keys](/spark-apis/authorization-api-keys.md).\
  The [Authorization - API keys](/spark-apis/authorization-api-keys.md#api-key-groups) must contain [Manage users](/tenant-administration/manage-users.md#user-groups) that are also assigned to [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md) `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 <a href="#api-request" id="api-request"></a>

Returns: Response from [#get-import-status](#get-import-status "mention").

```shellscript
POST /{tenant}/api/v4/import
```

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the  <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr></tbody></table>

### Request body <a href="#request-body" id="request-body"></a>

`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` | <p>Array of services modify objects. If not provided, it is assumed that the destination is taken from the source <code>folder</code> and <code>service</code> name.</p><p>The primary use of this parameter is to modify the destination of the exported service. Settings will apply only to the noted services.</p><p>JSON Array of the imported service settings:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> <code>{folder}/{service}</code> reference the service provided in the source.</li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> <code>{folder}/{service}</code> format to change destination <code>folder</code> and <code>service</code>. If omitted assume the same as <code>service\_uri\_source</code>.</li><li><code>update\_version\_type</code> <code>major</code>, <code>minor</code>, or <code>patch</code>, if not provided assume <code>minor</code> as default. This only applies when <code>services\_existing</code> is <code>add\_version</code>. Alternatively if <code>copy</code> is provided, then Spark will try to use the exact same semantic versions as the source.</li></ul><p>See the sample request for an example.</p> |
| `services_existing`      | <p>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.</p><ul><li>The default value is <code>abort</code> which means the import will fail if there is already an existing service with in the specified destination folder and service.</li><li><p><code>replace</code> means the entire service will be removed and replaced with the service versions in the imported file. <mark style="color:red;"><strong>Note that the previous API Call History for the service will no longer be accessible.</strong></mark></p><ul><li>If there are existing overlapping semantic versions between the destination and source, this will maintain the existing <code>version\_id</code>.</li></ul></li><li><code>add\_version</code> means that any existing services will be updated with the service versions included in the file.</li></ul>                                                                                                                                                                                                                                                                      |
| `source_system`          | <p>Tag API call.</p><p>Example: <code>mycicd</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `correlation_id`         | <p>Tag API call.</p><p>Example: <code>456</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### 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`.

```sh
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`

```json
{
	"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 <a href="#request_data" id="request_data"></a>

`HTTP 200 OK` `Content-Type: application/json`

Returns the response from [#get-import-status](#get-import-status "mention").

## `GET` import status

Returns: `status` response.

{% code overflow="wrap" %}

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

{% endcode %}

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the  <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr><tr><td><code>jobId</code> *</td><td><code>id</code> from <a data-mention href="#api-request-1">#api-request-1</a>.</td></tr></tbody></table>

### Response <a href="#request-body" id="request-body"></a>

Similar to the [Export](/spark-apis/impex-apis/export.md) API [Export](/spark-apis/impex-apis/export.md#request-body), with the following differences:

| Key                        | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outputs.services`         | <p>Array of the imported services sorted by <code>folder\_source</code>, <code>service\_source</code>:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}</code></li><li><code>folder\_source</code></li><li><code>service\_source</code></li><li><code>service\_id\_source</code></li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}</code></li><li><code>folder\_destination</code></li><li><code>service\_destination</code></li><li><code>service\_id\_destination</code></li><li><p><code>status</code>:</p><ul><li><code>added</code> service did not exist and it was added.</li><li><code>replaced</code> service exists and was replaced.</li><li><code>updated</code> service exists and new service versions were added.</li></ul></li></ul>                                                                                                                                                                                       |
| `outputs.service_versions` | <p>Array of the imported service versions sorted by <code>folder\_source</code>, <code>service\_source</code>, <code>version\_source</code>:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}\[{version}]</code></li><li><code>folder\_source</code></li><li><code>service\_source</code></li><li><code>version\_source</code> (semantic version)</li><li>service\_id\_source (not possible to get this value)</li><li><code>version\_id\_source</code></li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}\[{version}]</code></li><li><code>folder\_destination</code></li><li><code>service\_destination</code></li><li><code>version\_destination</code></li><li><code>service\_id\_destination</code></li><li><code>version\_id\_destination</code></li><li><p><code>status</code>:</p><ul><li><code>added</code> service version was added.</li><li><code>replaced</code> service version existed and was replaced.</li></ul></li></ul> |

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

```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](#get-import-status "mention").

{% code overflow="wrap" %}

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

{% endcode %}

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>environment</code> *</td><td>Environment is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL.</td></tr><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the  <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr><tr><td><code>jobId</code> *</td><td><code>id</code> from <a data-mention href="#api-request-1">#api-request-1</a>.</td></tr></tbody></table>

### Request

&#x20;`Content-Type: application/json`

```json
{"import_status":"cancelled"}
```

### Response

`HTTP 200 OK` `Content-Type: application/json`

Returns the response from [#get-import-status](#get-import-status "mention").

## `GET` import status across the tenant

Get information about import jobs that are `in_progress_imports` or `recent_imports` within the past `1 h`.&#x20;

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.

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

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the  <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr></tbody></table>

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

```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": "myuser@mydomain.com",
                "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
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherent.global/spark-apis/impex-apis/import.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.