> 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-apis.md).

# Execute APIs

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

## 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 APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"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 APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"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 APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"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

> \`request\_meta\` must define the service reference.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"summary":"Generic execute endpoint","description":"`request_meta` must define the service reference.","operationId":"postv3Execute","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Generic v3 endpoint

> \`request\_meta\` must define the service reference.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"summary":"Generic v3 endpoint","description":"`request_meta` must define the service reference.","operationId":"postv3","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV3"},"responses":{"200":{"$ref":"#/components/responses/executeV3"}}}}}}
```

## Reference for custom endpoints

> \`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 APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in 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. 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. 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 has effective start and effective until 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 until 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** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"array_outputs":{"type":["null","string"],"description":"Comma-separated string of `Xoutput` ranges to return in the JSON array format. Use `*` 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 from call to call due to the need to generate and populate the Excel file."},"xreport_options":{"$ref":"#/components/schemas/v3XReportOptions"},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode in which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."},"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 is 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 number 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."},"xconnector_parse_mode":{"type":["null","integer"],"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 APIs"],"summary":"Reference for custom endpoints","description":"`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"}}}}}}
```

## Generic v4 execute endpoint

> The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.\<br>\<br> This endpoint should not be used for a very large number of input records because there is an execution time limit of \`55 s\` and an error will be returned. For very large numbers of input records, we recommend using applications that utilize the \[Batch APIs]\(<https://docs.coherent.global/spark-apis/batch-apis>).

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute APIs","description":"Execute the calculation from a Spark service. Depending on the desired reference parameter, different URIs are available. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/) for more details.<br><br> The code snippet for your Spark service APIs can be found in the **API Tester** **Code Snippets**."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironment"}}}],"security":[{"bearerAuth":[]},{"tenantName":[],"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"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 sign-in URL and also available in the user menu.","schema":{"type":"string"}}},"requestBodies":{"executeV4":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"For JSON arrays format, the first row contains the name of the inputs in an array, and subsequent rows define the values for the corresponding records."},{"type":"object","description":"For JSON objects format, each element is an object containing key-value pairs that will be passed to the fields identified as Xinput in the workbook."}]},"description":"Array of input records."},"service":{"type":["null","string"],"description":"URI or `service_id` of the service being called."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"version_id of the requested service version. This will be resolved by Spark the quickest."},"version_by_timestamp":{"type":["null","string"],"anyOf":[{"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 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 has effective start and effective until 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 until 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."},"output":{"type":["null","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."},"subservice":{"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."},"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**."},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in **API Call History**."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default, this uses the setting defined in **Service Documentation** **Version details** **Default service type**.","enum":["Neuron","XConnector"]},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions is 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."},"xconnector_parse_mode":{"type":["null","integer"],"enum":[0,1],"description":"Integer to define the mode of which `XConnector` response are parsed. `null` or `0` is the first implementation, `1` supports proper table parsing."}}}}}}},"responses":{"executeV4":{"description":"OK","headers":{"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":{"properties":{"outputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"Array of JSON arrays."},{"type":"object","description":"Array of JSON objects."}]},"description":"Array of outputs. The elements of the array correspond to the input request records. Outputs will be formatted in a similar way to the inputs. The layout of outputs depends on whether the inputs consisted of an array of JSON objects or JSON arrays."},"process_time":{"type":["null","array"],"items":{"type":"number"},"description":"Time for Spark to process the API call in `ms`. The elements of the array correspond to the input request records."},"warnings":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of warnings. The elements of the array correspond to the input request records."},"errors":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of errors. The elements of the array correspond to the input request records."},"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."},"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_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"correlation_id":{"type":["null","string"],"description":"Value from request body."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."},"xconnector_parse_mode":{"type":["null","string"],"description":"Value from request body."}}}}}}}},"paths":{"/{tenant}/api/v4/execute":{"post":{"tags":["Execute APIs"],"summary":"Generic v4 execute endpoint","description":"The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.<br><br> This endpoint should not be used for a very large number of input records because there is an execution time limit of `55 s` and an error will be returned. For very large numbers of input records, we recommend using applications that utilize the [Batch APIs](https://docs.coherent.global/spark-apis/batch-apis).","operationId":"postv4Execute","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV4"},"responses":{"200":{"$ref":"#/components/responses/executeV4"}}}}}}
```