# Service APIs
APIs for managing Spark services.
## Upload Excel file to Spark
> Returns \`nodegen\_compilation\_jobid\`, \`original\_file\_documentid\`, and \`engine\_file\_documentid\` which are needed to Publish service.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServiceUpload.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}},"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/upload":{"post":{"tags":["Service APIs"],"summary":"Upload Excel file to Spark","description":"Returns `nodegen_compilation_jobid`, `original_file_documentid`, and `engine_file_documentid` which are needed to Publish service.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServiceUpload.json` or `Spark.AllEncompassingProxy.json`.","operationId":"postFoldersServicesUpload","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"serviceFile":{"type":"string","format":"binary","description":"Service file to be uploaded."},"engineUploadRequestEntity":{"type":"object","description":"Request parameters for the engine upload. These settings may be overridden during Publish.","properties":{"request_data":{"type":"object","properties":{"version_difference":{"anyOf":[{"type":"null"},{"type":"string","enum":["major","minor","patch"]}],"description":"Parameter is required but ignored. Value is set in Publish service.","default":"minor"},"effective_start_date":{"anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Parameter is required but ignored. Value is set in Publish service.","default":"2000-01-01"},"effective_end_date":{"anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Parameter is required but ignored. Value is set in Publish service.","default":"2100-01-01"},"compiler_version":{"type":["null","string"],"description":"Neuron version to use for compilation if specified. Reference Neuron release history."},"compiler_type":{"type":["null","string"],"enum":["MaintainVersion","TenantDefault","StableLatest","ReleaseCandidate"],"description":"Sets the default method to choose the Neuron version for the next upload."}},"required":["version_difference","effective_start_date","effective_end_date"]}},"required":["request_data"]}},"required":["serviceFile","engineUploadRequestEntity"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Check compilation status
> Get the Neuron "Excel-to-code" compilation status of the Excel upload. This can be run after Upload Excel file to Spark.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServiceCompilationProgress.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}},"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}},"jobId":{"name":"jobId","in":"path","required":true,"description":"`job_id` associated from `POST` job.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/getcompilationprogess/{jobId}":{"get":{"tags":["Service APIs"],"summary":"Check compilation status","description":"Get the Neuron \"Excel-to-code\" compilation status of the Excel upload. This can be run after Upload Excel file to Spark.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServiceCompilationProgress.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getFoldersServicesGetCompilationProgress","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"},{"$ref":"#/components/parameters/jobId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Publish service
> Complete the actions to create a Spark service after Upload Excel file to Spark. Compilation must be completed before publishing, Check compilation status.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServicePublish.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}},"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/publish":{"post":{"tags":["Service APIs"],"summary":"Publish service","description":"Complete the actions to create a Spark service after Upload Excel file to Spark. Compilation must be completed before publishing, Check compilation status.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServicePublish.json` or `Spark.AllEncompassingProxy.json`.","operationId":"postFoldersServicesPublish","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"original_file_documentid":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`id` from Upload Excel to Spark."},"engine_file_documentid":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`id` from Upload Excel to Spark."},"draft_service_name":{"type":["null","string"],"description":"Target service name overrides `service` from Upload Excel file to Spark."},"version_label":{"type":["null","string"],"description":"Version label for service version. This will appear in the user interface dropdowns."},"release_note":{"type":["null","string"],"description":"Release note for service version."},"effective_start_date":{"anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to set the parameters for the version resolution capability. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601."},"effective_end_date":{"type":"string","anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to set the parameters for the version resolution capability. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601."},"version_difference":{"anyOf":[{"type":"null"},{"type":"string","enum":["major","minor","patch","custom"]}],"description":"`major`, `minor`, `patch` or `custom` method of updating [Semantic Versioning](https://semver.org/)."},"should_trck_user_action":{"type":"boolean","description":"String boolean to set whether an event would be recorded for this action. Events are visible in the _Options_ _Event viewer_."},"tags":{"type":["null","string"],"description":"Comma separated string of tags."},"description":{"type":["null","string"],"description":"Description for service version."},"semantic_version":{"type":["null","string"],"description":"Semantic version needs to be popualted if `version_difference` is `custom`."}},"required":["original_file_documentid","engine_file_documentid","draft_service_name"]}},"required":["request_data"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## List service versions
> Get details about every service version.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.GetVersions.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}}}},"paths":{"/api/v1/product/{folder}/engines/getversions/{service}":{"get":{"tags":["Service APIs"],"summary":"List service versions","description":"Get details about every service version.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.GetVersions.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getProductEnginesGetVersions","parameters":[{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Get details for a service version
> Returns detailed information about the Excel workbook, upload details, Neuron compilation outputs, mapped \`Xinput\`, \`Xoutput\`, and metadata, etc.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServiceGet.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}},"versionId":{"name":"versionId","in":"path","required":true,"description":"`version_id` of the requested service.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/v1/product/{folder}/engines/get/{service}/{versionId}":{"get":{"tags":["Service APIs"],"summary":"Get details for a service version","description":"Returns detailed information about the Excel workbook, upload details, Neuron compilation outputs, mapped `Xinput`, `Xoutput`, and metadata, etc.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServiceGet.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getProductEnginesGet","parameters":[{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"},{"$ref":"#/components/parameters/versionId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Check compilation status
> Check whether a service exists.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServiceExists.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}},"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/exists":{"get":{"tags":["Service APIs"],"summary":"Check compilation status","description":"Check whether a service exists.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServiceExists.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getFoldersServicesExists","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Download the Excel file from a Spark service
> If using an API key, the API key group must contain user groups that are also assigned to \`Spark.DownloadServiceByVersionId.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}},"versionId":{"name":"versionId","in":"path","required":true,"description":"`version_id` of the requested service.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/v1/product/{folder}/engines/{service}/download/{versionId}":{"get":{"tags":["Service APIs"],"summary":"Download the Excel file from a Spark service","description":"If using an API key, the API key group must contain user groups that are also assigned to `Spark.DownloadServiceByVersionId.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getProductEnginesDownload","parameters":[{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"},{"$ref":"#/components/parameters/versionId"},{"name":"filename","in":"query","description":"Name of the downloaded file. If not provided, Spark will use an appropriate name.","schema":{"type":"string"}},{"name":"type","in":"query","description":"`ca` returns the Coherent Assistant enhanced version of the workbook. If not provided, the original workbook will be downloaded.","schema":{"type":["null","string"],"enum":["ca","null"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}}}}}}}
```
## Download Swagger
> Get \[Swagger]\() (OpenAPI 2.0) documentation for a Spark service.\
\
If using an API key, the API key group must contain user groups that are also assigned to \`Spark.DownloadSwagger.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}},"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}},"versionId":{"name":"versionId","in":"path","required":true,"description":"`version_id` of the requested service.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/downloadswagger/{category}/{isDownload}/{versionId}":{"get":{"tags":["Service APIs"],"summary":"Download Swagger","description":"Get [Swagger](https://swagger.io/specification/v2/) (OpenAPI 2.0) documentation for a Spark service.
If using an API key, the API key group must contain user groups that are also assigned to `Spark.DownloadSwagger.json` or `Spark.AllEncompassingProxy.json`.","operationId":"getFoldersServicesDownloadSwagger","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"},{"name":"category","in":"path","required":true,"description":"`All` for all subservices or a list of the requested subservices.","schema":{"type":"string"}},{"name":"isDownload","in":"path","required":true,"description":"`true` for integrating with this endpoint.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/versionId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Delete service
> If using an API key, the API key group must contain user groups that are also assigned to \`Spark.ServiceDelete.json\` or \`Spark.AllEncompassingProxy.json\`.
```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Service APIs","description":"APIs for managing Spark services."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"folder":{"name":"folder","in":"path","required":true,"description":"Folder associated with the API call.","schema":{"type":"string"}},"service":{"name":"service","in":"path","required":true,"description":"Service associated with the API call.","schema":{"type":"string"}}}},"paths":{"/api/v1/product/{folder}/engines/delete/{service}":{"delete":{"tags":["Service APIs"],"summary":"Delete service","description":"If using an API key, the API key group must contain user groups that are also assigned to `Spark.ServiceDelete.json` or `Spark.AllEncompassingProxy.json`.","operationId":"deleteProductEnginesDelete","parameters":[{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
---
# 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/spark-openapi-specification/service-apis.md?ask=
```
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.