Skip to main content
Decision Control exposes RESTful APIs for model management, decision execution, and system monitoring. This document provides API reference documentation, authentication patterns, integration examples, and error handling guidance for integrating Decision Control into your enterprise architecture.

API Architecture

Decision Control provides two API surfaces: Decision Control Management API: Model lifecycle operations (create, version, publish, execute) exposed by each Decision Control environment instance. Actuator API: Health checks, metrics, and operational endpoints for monitoring and observability. All APIs require OAuth2 Bearer token authentication via Keycloak and return JSON responses with standard HTTP status codes. Governance workflows — approvals, four-eyes enforcement, and audit trails — are managed through Aletyx Decision Control Tower (Keystone Edition). See the Aletyx Decision Control Tower documentation for governance features.

Authentication

Obtaining an Access Token

Decision Control uses OAuth2 Authorization Code flow with PKCE for browser-based clients and Client Credentials flow for service-to-service integration.

Using Access Tokens

Include the access token in the Authorization header for all API requests:
Token ExpirationAccess tokens expire after 5 minutes by default. Implement automatic token refresh using the refresh token to avoid authentication failures. See Token Refresh for details.

Token Refresh

Refresh tokens before expiration to maintain continuous authentication:

Decision Control Management API

The Management API provides operations for creating, versioning, publishing, and executing DMN models. Each environment (dev, test, prod) exposes its own Management API instance.

Base URLs

Units API

Units are top-level organizational containers for decision models. They represent logical groupings like business domains, applications, or functional areas.

List All Units

Response:
Date FormatThe dateCreated field uses Java LocalDateTime array format: [year, month, day, hour, minute, second, nanosecond]. Convert to ISO 8601 for display: 2025-01-15T10:30:00.000Z.
Example:

Create New Unit

Response: 201 Created
Example:

Get Unit by ID

Response:

Update Unit

Delete Unit

Response: 204 No Content
Cascade DeleteDeleting a unit removes all associated versions and models. This operation cannot be undone. Consider setting status: "DISABLED" instead for soft deletion.

Versions API

Versions represent numbered releases of decision models within a unit. They enable versioning, rollback capabilities, and environment promotion tracking.

List Versions for Unit

Response:
Example:

Create New Version

Response: 201 Created

Publish Version

Marks a version as published and ready for execution or promotion.
Response: 200 OK
Example:

Models API

Models are individual DMN files within a version. Each model contains decision logic, decision tables, and business knowledge models.

List Models for Version

Response:
Example:

Get Model Content

Retrieves the complete DMN XML for a model.
Response: 200 OK

Upload Model

Creates or updates a model within a version.
Response: 201 Created Example:

Decision Execution API

Execute published DMN models with input data and receive decision results.

Execute Decision

Response: 200 OK
Example:

Batch Execution

Execute decisions for multiple input contexts in a single request.
Response: 200 OK

Health and Monitoring API

Health Checks

Response:
Example:

Metrics

Returns list of available metrics:
Get specific metric:
Response:

Error Handling

HTTP Status Codes

Decision Control uses standard HTTP status codes:

Error Response Format

Decision Control returns a minimal JSON body with the failure message in the error field, e.g.:
The HTTP status code is the primary signal; clients should branch on it and surface the error text to users or logs. Decision Control does not emit machine-readable error codes, timestamps, or request IDs in the response body.

Retry Strategy

For transient errors (5xx status codes), implement exponential backoff:

Integration Examples

Node.js Integration

Python Integration

Java Integration

Next Steps