Execute API (v4)

Execute multiple calculations from a Spark service. Supports synchronous batching enabling multiple requests to be submitted at the same time. See the documentation for more details. This endpoint should not be used for very large number of input records because there is an execution time limit of 55 s and an error will be returned. For very large numbers of input records, we recommend using applications that utilize the Batch APIs.

Generic execute endpoint

post

The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time. If using an API key, the API key group must contain user groups that are also assigned to Spark.SyncBatch.json or Spark.AllEncompassingProxy.json.

Authorizations

bearerTokensyntheticKey & tenantName

AuthorizationstringRequired

Bearer token can be accessed from the user menu.

Path parameters

tenantstringRequired

Tenant is part of your login URL and also available in the user menu.

Example: mytenantname

Body

application/json

servicestring · nullableOptional

URI or service_id of the service being called.

Example: stocks/NVDA

version_idone ofOptional

version_id of the requested service version. This will be resolved by Spark the quickest.

Example: 8183f03a-57ca-4889-adae-0630be54bd87

nullOptional

or

string · uuidOptional

version_by_timestampany of · nullableOptional

Timestamp to resolve the service version. Use Timestamp converter to convert dates to ISO 8601. When call to a service is made using the service_uri or service_id this is used to determine the latest version of a service which 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.

Example: 2022-10-30

nullOptional

or

string · dateOptional

or

string · date-timeOptional

subservicestring · nullableOptional

Comma separated string of subservice names. When this is not specified or set as #Default#, outputs not related to subservices are shown.

Example: subservice1 will only show the the outputs from subservice1.

source_systemstring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: mycicd

correlation_idstring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: 456

call_purposestring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: admin system p

compiler_typenull,string · enum · nullableOptional

Calculation engine for the request. By default this uses the setting defined in Service Documentation Default service type.

Example: NeuronPossible values:

manual_nowinteger · nullableOptional

Default behavior for Excel NOW() and TODAY() functions are to return the value based upon server time. If a Unix epoch time is provided, then that will be used to derive the current time and date instead.

Example: 1650593119

Responses

200

OK

application/json

post

/{tenant}/api/v4/execute

HTTPcURLJavaScriptPython

POST /{tenant}/api/v4/execute HTTP/1.1
Host: excel.myenvironmentname.coherent.global
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 320

{
  "inputs": [
    [
      "A11",
      "A33",
      "A44"
    ],
    [
      10,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          10,
          20,
          30
        ],
        [
          110,
          120,
          130
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          10,
          20,
          30,
          40
        ],
        [
          110,
          120,
          130,
          140
        ]
      ]
    ],
    [
      20,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          20,
          40,
          60
        ],
        [
          220,
          240,
          260
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          20,
          40,
          60,
          80
        ],
        [
          220,
          240,
          260,
          280
        ]
      ]
    ]
  ],
  "service": "MyFolder/BlockParty",
  "call_purpose": "Array of JSON arrays"
}

200

OK

{
  "outputs": [
    [
      "A11",
      "A33",
      "A44"
    ],
    [
      20,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          20,
          40,
          60
        ],
        [
          220,
          240,
          260
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          20,
          40,
          60,
          80
        ],
        [
          220,
          240,
          260,
          280
        ]
      ]
    ],
    [
      40,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          40,
          80,
          120
        ],
        [
          440,
          480,
          520
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          40,
          80,
          120,
          160
        ],
        [
          440,
          480,
          520,
          560
        ]
      ]
    ]
  ],
  "process_time": [
    1,
    1
  ],
  "warnings": [
    null,
    null
  ],
  "errors": [
    [
      {
        "source_path": "$.Input.A11",
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "message": "Input Not Valid",
        "additional_details": "BlockParty"
      }
    ],
    [
      {
        "source_path": "$.Input.A11",
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "message": "Input Not Valid",
        "additional_details": "BlockParty"
      }
    ]
  ],
  "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81",
  "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43",
  "version": "0.1.0",
  "call_id": "bb4cf8fb-358e-4fc8-9a0b-19dbdb219e81",
  "compiler_version": "1.16.0",
  "correlation_id": null,
  "request_timestamp": "2024-03-12T05:14:37.912Z"
}

Public API Generic execute endpoint

post

The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time. If using an API key, the API key group must contain user groups that are also assigned to Spark.SyncBatch.json or Spark.AllEncompassingProxy.json.

Authorizations

bearerTokentenantNamesyntheticKey

AuthorizationstringRequired

Bearer token can be accessed from the user menu.

Path parameters

tenantstringRequired

Tenant is part of your login URL and also available in the user menu.

Example: mytenantname

Body

application/json

servicestring · nullableOptional

URI or service_id of the service being called.

Example: stocks/NVDA

version_idone ofOptional

version_id of the requested service version. This will be resolved by Spark the quickest.

Example: 8183f03a-57ca-4889-adae-0630be54bd87

nullOptional

or

string · uuidOptional

version_by_timestampany of · nullableOptional

Timestamp to resolve the service version. Use Timestamp converter to convert dates to ISO 8601. When call to a service is made using the service_uri or service_id this is used to determine the latest version of a service which 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.

Example: 2022-10-30

nullOptional

or

string · dateOptional

or

string · date-timeOptional

subservicestring · nullableOptional

Comma separated string of subservice names. When this is not specified or set as #Default#, outputs not related to subservices are shown.

Example: subservice1 will only show the the outputs from subservice1.

source_systemstring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: mycicd

correlation_idstring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: 456

call_purposestring · nullableOptional

Tag API call. Can be queried in API Call History.

Example: admin system p

compiler_typenull,string · enum · nullableOptional

Calculation engine for the request. By default this uses the setting defined in Service Documentation Default service type.

Example: NeuronPossible values:

manual_nowinteger · nullableOptional

Default behavior for Excel NOW() and TODAY() functions are to return the value based upon server time. If a Unix epoch time is provided, then that will be used to derive the current time and date instead.

Example: 1650593119

Responses

200

OK

application/json

post

/{tenant}/api/v4/public/execute

HTTPcURLJavaScriptPython

POST /{tenant}/api/v4/public/execute HTTP/1.1
Host: excel.myenvironmentname.coherent.global
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 320

{
  "inputs": [
    [
      "A11",
      "A33",
      "A44"
    ],
    [
      10,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          10,
          20,
          30
        ],
        [
          110,
          120,
          130
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          10,
          20,
          30,
          40
        ],
        [
          110,
          120,
          130,
          140
        ]
      ]
    ],
    [
      20,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          20,
          40,
          60
        ],
        [
          220,
          240,
          260
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          20,
          40,
          60,
          80
        ],
        [
          220,
          240,
          260,
          280
        ]
      ]
    ]
  ],
  "service": "MyFolder/BlockParty",
  "call_purpose": "Array of JSON arrays"
}

200

OK

{
  "outputs": [
    [
      "A11",
      "A33",
      "A44"
    ],
    [
      20,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          20,
          40,
          60
        ],
        [
          220,
          240,
          260
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          20,
          40,
          60,
          80
        ],
        [
          220,
          240,
          260,
          280
        ]
      ]
    ],
    [
      40,
      [
        [
          "A1",
          "A2",
          "A3"
        ],
        [
          40,
          80,
          120
        ],
        [
          440,
          480,
          520
        ]
      ],
      [
        [
          "A1",
          "B.B1",
          "B.B2",
          "C1"
        ],
        [
          40,
          80,
          120,
          160
        ],
        [
          440,
          480,
          520,
          560
        ]
      ]
    ]
  ],
  "process_time": [
    1,
    1
  ],
  "warnings": [
    null,
    null
  ],
  "errors": [
    [
      {
        "source_path": "$.Input.A11",
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "message": "Input Not Valid",
        "additional_details": "BlockParty"
      }
    ],
    [
      {
        "source_path": "$.Input.A11",
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "message": "Input Not Valid",
        "additional_details": "BlockParty"
      }
    ]
  ],
  "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81",
  "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43",
  "version": "0.1.0",
  "call_id": "bb4cf8fb-358e-4fc8-9a0b-19dbdb219e81",
  "compiler_version": "1.16.0",
  "correlation_id": null,
  "request_timestamp": "2024-03-12T05:14:37.912Z"
}