> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/spark-apis/spark-openapi-specification/execute-api-v3.md).

# Execute API (v3)

Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.\
\
The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI.

## Reference by folder and service

> \`request\_meta\` \`version\_id\`, \`version\`, and \`transaction\_date\` can be used for version resolution.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/folders/{folder}/services/{service}/execute":{"post":{"tags":["Execute API (v3)"],"summary":"Reference by folder and service","description":"`request_meta` `version_id`, `version`, and `transaction_date` can be used for version resolution.","operationId":"postv3FoldersServicesExecute","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Reference by service\_id

> \`request\_meta\` \`version\_id\`, \`version\`, and \`transaction\_date\` can be used for version resolution.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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"}},"serviceId":{"name":"serviceId","in":"path","required":true,"description":"`service_id` of the requested service.","schema":{"type":"string","format":"uuid"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/service/{serviceId}":{"post":{"tags":["Execute API (v3)"],"summary":"Reference by service_id","description":"`request_meta` `version_id`, `version`, and `transaction_date` can be used for version resolution.","operationId":"postv3Service","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/serviceId"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Reference by version\_id

> \`version\_id\` is the most direct service version reference.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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"}},"versionId":{"name":"versionId","in":"path","required":true,"description":"`version_id` of the requested service.","schema":{"type":"string","format":"uuid"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/version/{versionId}":{"post":{"tags":["Execute API (v3)"],"summary":"Reference by version_id","description":"`version_id` is the most direct service version reference.","operationId":"postv3Version","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/versionId"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Generic execute endpoint

> Service reference must be defined in the \`request\_meta\`.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/execute":{"post":{"tags":["Execute API (v3)"],"summary":"Generic execute endpoint","description":"Service reference must be defined in the `request_meta`.","operationId":"postv3Execute","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Generic v3 endpoint

> Service reference must be defined in the request\_meta.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."}},"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"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3":{"post":{"tags":["Execute API (v3)"],"summary":"Generic v3 endpoint","description":"Service reference must be defined in the request_meta.","operationId":"postv3","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Public API reference by folder and service

> \`request\_meta\` \`version\_id\`, \`version\`, and \`transaction\_date\` can be used for version resolution.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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."},"syntheticKey":{"type":"apiKey","in":"header","name":"x-synthetic-key","description":"API key instance."}},"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"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/public/folders/{folder}/services/{service}/execute":{"post":{"tags":["Execute API (v3)"],"summary":"Public API reference by folder and service","description":"`request_meta` `version_id`, `version`, and `transaction_date` can be used for version resolution.","operationId":"postv3PublicFoldersServicesExecute","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/folder"},{"$ref":"#/components/parameters/service"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Public API reference by service\_id

> \`request\_meta\` \`version\_id\`, \`version\`, and \`transaction\_date\` can be used for version resolution.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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."},"syntheticKey":{"type":"apiKey","in":"header","name":"x-synthetic-key","description":"API key instance."}},"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"}},"serviceId":{"name":"serviceId","in":"path","required":true,"description":"`service_id` of the requested service.","schema":{"type":"string","format":"uuid"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/public/service/{serviceId}":{"post":{"tags":["Execute API (v3)"],"summary":"Public API reference by service_id","description":"`request_meta` `version_id`, `version`, and `transaction_date` can be used for version resolution.","operationId":"postv3PublicService","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/serviceId"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Public API reference by version\_id

> \`version\_id\` is the most direct service version reference.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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."},"syntheticKey":{"type":"apiKey","in":"header","name":"x-synthetic-key","description":"API key instance."}},"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"}},"versionId":{"name":"versionId","in":"path","required":true,"description":"`version_id` of the requested service.","schema":{"type":"string","format":"uuid"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/public/version/{versionId}":{"post":{"tags":["Execute API (v3)"],"summary":"Public API reference by version_id","description":"`version_id` is the most direct service version reference.","operationId":"postv3PublicVersion","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/versionId"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Reference for custom endpoints

> The \`request\_meta\` \`version\_id\`, \`version\`, and \`transaction\_date\` can be used for version resolution.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v3)","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URI are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3) for more details.<br><br> The code snippet for your Spark service APIs can be found in the API Tester Code Snippets using the OpenAI."}],"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"}},"urlsuffix":{"name":"urlsuffix","in":"path","required":true,"description":"Custom endpoints path.","schema":{"type":"string"}}},"requestBodies":{"executeV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiRequestEntity"}}}}},"schemas":{"v3EngineApiRequestEntity":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/v3EngineRequestData"},"request_meta":{"$ref":"#/components/schemas/v3EngineRequestMeta"}},"additionalProperties":false},"v3EngineRequestData":{"type":["null","object"],"properties":{"inputs":{"$ref":"#/components/schemas/v3ServiceInputs"}},"additionalProperties":false},"v3ServiceInputs":{"type":["null","object"],"description":"Object that contains key value pairs that will be passed to the fields identified as Xinput in the workbook. See documentation for more information."},"v3EngineRequestMeta":{"type":["null","object"],"properties":{"service_uri":{"type":["null","string"],"description":"Reference to service location in the format of `folders/{folder}/services/{service}`. This does not specify the version of the service returned. This can be done so by including `transaction_date` or `version`."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the requested service. This does not specify the version of the service returned. This can be done so by using `transaction_date` or `version`."},"version":{"type":["null","string"],"description":"Semantic version number which corresponds to the version number shown in the Spark user interface `{Major revision}.{Minor revision}.{Patch revision}`."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the requested service version. This takes precedence over `service_uri`, `service_id`, `transaction_date`, `version`."},"transaction_date":{"oneOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When a call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"requested_output":{"oneOf":[{"type":"null"},{"type":"string"},{"type":"array","items":{"type":["null","string"]}}],"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"service_category":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"This is a string list of `Xoutput` ranges to return in the JSON array format. Using `*` can be used to denote all of the outputs."},"response_data_inputs":{"type":["null","boolean"],"description":"Boolean to enable the echo of request_data.inputs into response_data.inputs. This is useful for consuming systems that want to store and analyze the API request and response data together."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` the XParameters to use with the Spark service."},"excel_file":{"type":["null","boolean"],"description":"When set to `true`, this returns a copy of the source Excel file with the `request_data` `input`s populated into the `Xinput` cells. The output is the same as the _Download as Excel (Legacy)_. For security, the use of this feature with API keys can be managed through the `Spark.DownloadServiceByCallId.json` feature permission. This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"debug_solve":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.solve_log` which contains the iterations for each `Xsolve` in the service."},"debug_xcall":{"type":["null","boolean"],"description":"Boolean to return `outputs.additional_outputs.xcall_log` which contains the tracing for the `Xcall` used in the execution of the service."},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."},"profile":{"type":["null","boolean"],"description":"Boolean to enable performance tracing. See documentation for more information."},"random_seed":{"type":["null","integer"],"description":"Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers."},"requested_output_regex":{"type":["null","string"],"description":"Regular expression string to denote the outputs to keep in the response. This is an advancement of `requested_output`. If both `requested_output` and `requested_output_regex` are specified, then an error will be raised."},"show_max_calc_chain":{"type":["null","boolean"],"description":"When the debug build is used, this is used to identify the longest calculation chain. See documentation for more information.","default":false},"top_n_profile":{"type":["null","integer"],"description":"When the debug build is used, this is used to adjust the of records returned from the performance tracing output."}},"additionalProperties":true},"v3XReportOptions":{"type":"object","properties":{"multiple_docs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return each `Xreport` sheet as a separate PDF. Default is `true`. If no `xreport_options` are used in the request, the default is `true`. If `xreport_options` are used in the request, then the default is `false`.","default":true},"page_numbers":{"type":["null","boolean"],"description":"Boolean to indicate whether to include page numbers. Default is `true`.","default":true},"produce_pdfs":{"type":["null","boolean"],"description":"Boolean to indicate whether to return the `Xreport` sheets as PDFs. Default is `true`.","default":true},"render_chart_texture_bars_as_images":{"type":["null","boolean"],"description":"Boolean to resolve an issue with borders appearing for dynamic chart images.","default":false}},"additionalProperties":false},"v3EngineApiResponseEntity":{"type":"object","properties":{"status":{"type":["null","string"],"description":"API response status."},"response_data":{"$ref":"#/components/schemas/v3EngineResponseData"},"response_meta":{"$ref":"#/components/schemas/v3EngineResponseMetadata"},"error":{"$ref":"#/components/schemas/v3ResponseError"},"traceEvents":{"type":["null","array"],"description":"Trace event data returned when \"`profile\": true`.","items":{"type":"object"}}},"additionalProperties":false},"v3EngineResponseData":{"type":"object","properties":{"outputs":{"$ref":"#/components/schemas/v3ServiceOutputs"},"warnings":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionValidation"},"description":"Array of warnings."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/v3EngineExecutionError"},"description":"Array of errors."},"inputs":{"type":["null","object"],"description":"Inputs from the request will be returned in the response if the `request_meta` `response_data_inputs` is `true`."},"trace":{"type":["null","object"]}},"additionalProperties":false},"v3ServiceOutputs":{"type":"object","description":"Object that contains key value pairs returned from the Spark service. See documentation for more information."},"v3EngineExecutionValidation":{"type":"object","description":"Object for describing validation warnings.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the validation message."},"message":{"type":["null","string"],"description":"Validation message."}},"additionalProperties":false},"v3EngineExecutionError":{"type":"object","description":"Object for describing errors.","properties":{"source_path":{"type":["null","string"],"description":"Source path of the error."},"message":{"type":["null","string"],"description":"Error message."},"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"additional_details":{"type":["null","string"],"description":"Additional error details."}},"additionalProperties":false},"v3EngineResponseMetadata":{"type":"object","properties":{"system":{"type":["null","string"],"description":"System that processed the request."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"process_time":{"type":["null","integer"],"description":"Time for Spark to process the API call in `ms`."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine used by Spark to process the request."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"source_hash":{"type":["null","string"]},"engine_id":{"type":["null","string"],"description":"Hash generated for this service."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"response_data_inputs":{"type":["null","boolean"],"description":"Value from Request body."},"array_outputs":{"type":["null","string"],"description":"Value from Request body."},"random_seed":{"type":["null","integer"],"description":"Value from Request body."},"show_max_calc_chain":{"type":["null","boolean"],"description":"Value from Request body."},"profile":{"type":["null","boolean"],"description":"Value from Request body."},"trace":{"type":["null","boolean"],"description":"Value from Request body."},"debug_build":{"type":["null","boolean"],"description":"Indicate if this service was compiled using the debug build."},"top_n_profile":{"type":["null","integer"],"description":"Value from Request body."},"parameterset_version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Value from Request body."},"debug_xcall":{"type":["null","boolean"],"description":"Value from Request body."},"debug_solve":{"type":["null","boolean"],"description":"Value from Request body."},"manual_now":{"type":["null","integer"],"description":"Value from Request body."}},"additionalProperties":true},"v3ResponseError":{"type":"object","description":"Object for describing errors.","properties":{"error_category":{"type":["null","string"],"description":"Error category."},"error_type":{"type":["null","string"],"description":"Error type."},"message":{"type":["null","string"],"description":"Error message."},"additional_details":{"type":["null","object"],"description":"Additional error details."}},"additionalProperties":false}},"responses":{"executeV3":{"description":"OK","headers":{"spark_total_time":{"schema":{"type":"number","description":"The time it took for Spark to process the inputs, perform the calculation, execute any `Ximage`, `Xreport`, `Xsolve` parameters in `ms`. This does not include any transit time."}},"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v3EngineApiResponseEntity"}}}}}},"paths":{"/{tenant}/api/v3/proxy/{urlsuffix}":{"post":{"tags":["Execute API (v3)"],"summary":"Reference for custom endpoints","description":"The `request_meta` `version_id`, `version`, and `transaction_date` can be used for version resolution.","operationId":"postv3ProxyUrlsuffix","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/urlsuffix"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```