Skip to main content

​
Base URL

https://api.lexq.io/api/v1/execution
The Execution API base URL (/api/v1/execution) is different from the Management API (/api/v1/partners). Use the correct base URL for each.

​
Authentication

Same API Key as the Management API. Include in every request: 
x-api-key: YOUR_API_KEY

​
Execution Modes

LexQ provides 4 execution modes. Choose the one that fits your use case:
ModeEndpointUse Case
Single GroupPOST /groups/{groupId}Standard single-order evaluation
Specific VersionPOST /groups/{groupId}/versions/{versionId}A/B testing, rollback testing
BatchPOST /groups/{groupId}/batchCart calculation, bulk product listing
CompositePOST /compositeMulti-group evaluation (discount + coupon + shipping)

​
Single Group Execution

Evaluates all active rules in the currently deployed version of a policy group. 
POST /groups/{groupId}

​
Request

curl -X POST https://api.lexq.io/api/v1/execution/groups/{groupId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "facts": {
      "user_id": "user_abc",
      "payment_amount": 150000,
      "customer_tier": "VIP"
    },
    "context": {
      "channel": "mobile-app"
    }
  }'
FieldTypeRequiredDescription
factsobject✅Input variables for rule evaluation
contextobjectAdditional metadata (not used in conditions, passed to actions)

​
Response

{
  "result": "SUCCESS",
  "data": {
    "outputVariables": {
      "discount_amount": 15000,
      "discount_applied": true
    },
    "executionTraces": [
      {
        "ruleName": "VIP 10% Discount",
        "ruleId": "...",
        "conditionMatched": true,
        "evaluatedExpression": "payment_amount >= 100000 AND customer_tier == VIP"
      }
    ],
    "decisionTraces": [
      {
        "ruleName": "VIP 10% Discount",
        "ruleId": "...",
        "selected": true,
        "reason": "CONDITION_MATCHED"
      }
    ]
  }
}

​
Idempotency

Include an Idempotency-Key header to prevent duplicate executions. If a request with the same key has already been processed, the original response is returned without re-executing the policy.

​
Specific Version Execution

Executes a specific version of a policy group, bypassing traffic routing. Useful for A/B testing a candidate version or testing a rollback target before switching. 
POST /groups/{groupId}/versions/{versionId}
Request and response formats are identical to Single Group Execution. The only difference is that the engine uses the specified version instead of the currently deployed one.
The version must be in ACTIVE (published) status. DRAFT versions cannot be executed via the Engine API — use Dry Run for testing DRAFT versions.

​
Batch Execution

Executes multiple fact sets against the same policy group in a single call. All requests in the batch are evaluated against the same version for consistency. 
POST /groups/{groupId}/batch

​
Request

curl -X POST https://api.lexq.io/api/v1/execution/groups/{groupId}/batch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "facts": { "user_id": "user_1", "payment_amount": 50000 } },
      { "facts": { "user_id": "user_2", "payment_amount": 150000 } },
      { "facts": { "user_id": "user_3", "payment_amount": 300000 } }
    ],
    "sharedContext": {
      "channel": "batch-job"
    }
  }'
FieldTypeRequiredDescription
requestsarray✅List of fact sets to evaluate
sharedContextobjectContext merged into every request

​
Response

{
  "result": "SUCCESS",
  "data": {
    "results": [
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] }
    ],
    "totalProcessingTimeMs": 45
  }
}
Results are returned in the same order as the input requests. Each item in the context is merged with sharedContext (per-request context takes priority on conflict).
Batch execution counts as 1 API call for TPS throttling, regardless of the number of items. However, billing is based on the total number of items.

​
Composite Execution

Evaluates the same facts against multiple policy groups in a single call. Useful when a transaction must pass through multiple policy checks simultaneously (e.g., product discount + cart coupon + shipping fee + membership points). 
POST /composite

​
Request

curl -X POST https://api.lexq.io/api/v1/execution/composite \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-composite" \
  -d '{
    "targetGroupIds": ["group-discount-id", "group-coupon-id", "group-shipping-id"],
    "facts": {
      "user_id": "user_abc",
      "payment_amount": 250000
    },
    "context": {
      "channel": "checkout"
    }
  }'
FieldTypeRequiredDescription
targetGroupIdsarray✅Policy group IDs to evaluate
factsobject✅Shared input facts for all groups
contextobjectShared context for all groups

​
Response

The response contains merged outputVariables, executionTraces, and decisionTraces from all evaluated groups. All target groups must be in ACTIVE status. If any group is DISABLED or not found, the entire request fails.

​
Requirements

Check which input facts a deployed version requires before calling the execution endpoint. Returns required keys, types, and an auto-generated sample request body. 
GET /groups/{groupId}/requirements

​
Request

curl https://api.lexq.io/api/v1/execution/groups/{groupId}/requirements \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept-Language: en"
The Accept-Language header controls the language of the usedBy descriptions (en or ko).

​
Response

{
  "result": "SUCCESS",
  "data": {
    "groupId": "...",
    "versionId": "...",
    "versionNo": 5,
    "requiredFacts": [
      {
        "key": "payment_amount",
        "type": "NUMBER",
        "displayName": "Payment Amount",
        "required": true,
        "description": "Payment Amount (System Default)",
        "usedBy": [
          "Condition [GREATER_THAN] in rule: VIP 10% Discount",
          "DISCOUNT action in rule: VIP 10% Discount"
        ]
      },
      {
        "key": "customer_tier",
        "type": "STRING",
        "displayName": "Customer Tier",
        "required": false,
        "usedBy": [
          "Condition [EQUALS] in rule: VIP 10% Discount"
        ]
      }
    ],
    "exampleRequest": {
      "facts": { "payment_amount": 50000, "customer_tier": "" },
      "context": { "reqTime": "2025-01-01T00:00:00Z" }
    }
  }
}
Call this endpoint before your first integration to see exactly which facts you need to provide. Copy the exampleRequest as a starting template and fill in real values.

​
System Facts

Every tenant has 7 pre-registered system facts available immediately after account creation. You do not need to create these manually:
KeyTypeRequiredDescription
user_idSTRING✅User identifier
payment_amountNUMBER✅Payment amount
phone_numberSTRINGPhone number
emailSTRINGEmail address
device_tokenSTRINGDevice token (for push notifications)
user_tagsLIST_STRINGUser tags
total_pointNUMBERCurrent point balance
Custom facts (e.g., customer_tier, order_region) must be registered via Fact Definitions before use.

​
Error Handling

HTTPCodeDescriptionAction
404POLICY_GROUP_NOT_FOUNDGroup ID doesn’t existVerify the group ID
400POLICY_GROUP_DISABLEDGroup is in DISABLED statusRe-enable the group
404POLICY_VERSION_NOT_FOUNDNo deployed version or version ID invalidDeploy a version first
400INVALID_INPUTMissing required factsCall /requirements to check
429—TPS limit exceededUpgrade plan or retry later

​
Next Steps

Dry Run

Test rules without side effects before going live.

Fact Definitions

Register custom input variables for your rules.