Execution API

The Execution API runs a deployed Decision Table, Ruleset, Scorecard, Workflow, HTTP Client, or Coding HubItem. The API key selects the solution and environment; the HubItem ID selects the decision to run.

Prerequisites

Before integration:

1. Deploy the HubItem and dependencies to the intended environment.
2. Verify the deployed version in environment progression.
3. Test the same payload in Testing Zone.
4. Create a solution API key for that environment with Execute access.
5. Copy the one-time secret into the calling application's secret store.
6. Record the organization ID, HubItem ID, and DecisionHub base URL.

The API cannot select an arbitrary version. It executes the version deployed in the API key's environment.

Create an API key

Open Solution → API Keys, select the environment, and choose Create new secret key.

Name

Use a name that identifies owner and purpose:

Loan Origination Service - Production

Permissions

• All grants the broad preset returned by the platform.
• Read only is unsuitable for executing decision logic.
• Restricted lets you choose the resource permission needed by the consumer.

Prefer Restricted with Execute for a service that only runs HubItems.

Expiration

Choose 1 hour, 1, 7, 30, 90, or 180 days, 1 year, or no expiration. Use the shortest practical period and establish rotation before expiry. “No expiration” still requires ownership review and revocation when the integration ends.

The full secret appears once. DecisionHub later shows only its prefix.

Send a request

curl --request POST \
  'https://YOUR_DECISIONHUB_HOST/executor/execute/ORGANIZATION_ID/HUBITEM_ID' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_KEY' \
  --data '{
    "applicationId": "APP-1042",
    "requestedAmount": 25000,
    "applicant": {
      "age": 34,
      "annualIncome": 78000,
      "existingDebt": 8500
    }
  }'

Expected illustrative response:

{
  "applicationId": "APP-1042",
  "status": "Approved",
  "riskBand": "Low",
  "approvedAmount": 25000
}

The actual shape is defined by the deployed output Data Model.

Debug requests

Append ?debug=true only for controlled diagnostics when the credential is permitted and payload capture is appropriate:

POST /executor/execute/{organizationId}/{hubItemId}?debug=true

Do not enable Debug routinely in production clients. Diagnostic data can contain intermediate business values and is governed by debug permission and retention.

Health check

GET /executor/health/{organizationId}

This verifies organization execution-service reachability. It does not prove that a particular HubItem is deployed, a key is authorized, or an external connector is healthy. Use a safe smoke execution for end-to-end verification.

Handle errors

Error category	Client behavior
Authentication/authorization	Do not retry blindly; check key, expiry, scope, solution, and environment
Input validation	Correct the payload or deployed model contract
HubItem unavailable	Verify ID and target-environment deployment
Rate limit	Respect the response and retry after an appropriate delay
Transient platform/service failure	Retry with bounded exponential backoff and idempotent business handling
External connector failure	Inspect Workflow trace and Integration Activity; apply the business fallback policy

Never log the complete API key. Sanitize request/response logging according to data policy.

Correlation and idempotency

Use a stable business identifier such as applicationId in the input and preserve correlation information returned or recorded by the platform. If a client retries after a timeout, design downstream external actions to avoid creating duplicate records or events.

Inspect usage

The API-key overview shows:

• active, expired, or disabled status;
• creation, expiry, and last-use time;
• per-hour, per-day, and per-month limits;
• current usage and total calls.

The Activity view summarizes calls, successes/failures, response time, and request/response sizes over the displayed period. Use Organization Statistics and Execution History for broader investigation.

Rotate or revoke

Rotate a key before expiry or whenever exposure is suspected:

1. Create/rotate to obtain a new secret.
2. Update the consumer's protected configuration.
3. Run a smoke test.
4. Confirm activity is arriving under the replacement.
5. Disable/delete the old credential according to the controls offered.

Revoke keys immediately when a service is retired or ownership is unknown.

Production integration checklist

• Request and response contracts are versioned and shared with the consumer.
• Key belongs to the correct solution and environment.
• Secret is stored server-side, not in browser/mobile code.
• Timeouts and bounded retries are configured.
• Business operations are safe under retry.
• Rate limits are understood.
• Correlation IDs/business IDs are logged safely.
• Alerts cover failure rate and latency.
• Rotation owner and expiry date are recorded.

DecisionHub's documented end-user integration uses API-key execution. The application does not expose a general OAuth, GraphQL, or webhook-management workflow in this interface.