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