Execute Engine¶

POST /jobs/execute/{tenant_slug}/{engine_slug}

Execute the active version of a rating engine. The job is processed asynchronously — the response returns immediately with a job_id you use to poll for results.

Required permission: can_execute

Path Parameters¶

Parameter	Type	Description
`tenant_slug`	string	Tenant identifier (e.g. `acme-insurance`)
`engine_slug`	string	Engine identifier (e.g. `property-calculator`)

Request Body¶

{
  "inputs": {
    "customerAge": 35,
    "propertyValue": 500000
  },
  "webhook_url": "https://your-app.com/webhooks/xlsxapi"
}

Field	Type	Required	Description
`inputs`	object	Yes	Key-value pairs matching the engine's `input_schema`
`webhook_url`	string	No	HTTP(S) URL to receive a POST when the job completes or fails

Response¶

202 Accepted

{
  "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "pending",
  "message": "Job queued for processing",
  "created_at": "2026-03-18T10:30:00Z"
}

Field	Type	Description
`job_id`	UUID	Unique identifier for polling status
`status`	string	Always `"pending"` on creation
`message`	string	Human-readable confirmation
`created_at`	datetime	ISO 8601 timestamp

Errors¶

400 Bad Request — input validation failed

{ "detail": "Input validation failed: 'customerAge' must be between 18 and 100" }

400 Bad Request — engine has no active version

{ "detail": "Engine has no active version" }

403 Forbidden — no execute permission

{ "detail": "Consumer does not have execute permission for this engine" }

403 Forbidden — IP not whitelisted

{ "detail": "Access denied: IP address not in whitelist" }

404 Not Found — tenant or engine not found

{ "detail": "Engine 'bad-slug' not found" }

Input Validation¶

If the engine has an input_schema defined (JSON Schema Draft 7), your inputs are validated before the job is queued. Use the Engine Info endpoint to discover the expected schema.

Tip

Validate inputs client-side before calling execute to avoid unnecessary API calls. The input_schema from the /about endpoint is a standard JSON Schema you can validate against in any language.

Example¶

curlPythonJavaScript

curl -X POST \
  https://api.xlsxapi.eu/jobs/execute/acme-insurance/property-calculator \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"customerAge": 35, "propertyValue": 500000}}'

import requests

resp = requests.post(
    "https://api.xlsxapi.eu/jobs/execute/acme-insurance/property-calculator",
    json={"inputs": {"customerAge": 35, "propertyValue": 500000}},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
job = resp.json()
print(job["job_id"])

const resp = await fetch(
  "https://api.xlsxapi.eu/jobs/execute/acme-insurance/property-calculator",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inputs: { customerAge: 35, propertyValue: 500000 },
    }),
  }
);
const job = await resp.json();
console.log(job.job_id);