Policy Execution - LexQ Docs

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

Any API key reaches this API, including one created with the default Execute only scope. Include it in every request:

x-api-key: YOUR_API_KEY

Execution Modes

LexQ provides 4 execution modes. Choose the one that fits your use case:

Mode	Endpoint	Use Case
Single Group	`POST /groups/{groupId}`	Standard single-order evaluation
Specific Version	`POST /groups/{groupId}/versions/{versionId}`	Testing a version without routing traffic to it
Batch	`POST /groups/{groupId}/batch`	Cart calculation, bulk product listing
Composite	`POST /composite`	Multi-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": {
      "userId": "user_abc",
      "paymentAmount": 150000,
      "customerTier": "VIP"
    },
    "context": {
      "channel": "mobile-app"
    }
  }'

Field	Type	Required	Description
`facts`	object	✅	Input variables for rule evaluation
`context`	object		Request metadata. Drives A/B routing and is recorded on the ledger

What context does. Two things, and neither follows from the name.

A/B routing reads it. When a policy group has an A/B test running, context.trafficKey decides which version serves the request. Omit it and the test version receives 0% of traffic. See Traffic Identity Key.
It is recorded. The whole object is stored on the execution ledger alongside the request, so it surfaces in execution history and audit views. Keep personal data out of it.

Values your rules evaluate belong in facts, not here. facts is the one input that fact definitions, the /requirements response, and the execution response all agree on. A value sent in context is outside that contract: it cannot be registered as a fact definition, it never appears in /requirements, and it is not returned in the response.

Response

{
  "result": "SUCCESS",
  "data": {
    "traceId": "2e31f2b8-...",
    "inputFacts": {
      "userId": "user_abc",
      "paymentAmount": 150000,
      "customerTier": "VIP"
    },
    "mutatedFacts": {
      "paymentAmount": 135000
    },
    "generatedVariables": {
      "paymentAmount__delta": -15000
    },
    "executionTraces": [
      {
        "tenantId": "acme-corp",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% Discount",
        "executedAt": "2026-04-27T09:44:10Z",
        "matched": true,
        "matchExpression": "(customerTier == 'VIP') && (paymentAmount >= 100000)",
        "inputFacts": {
          "customerTier": "VIP",
          "paymentAmount": 150000
        },
        "generatedActions": [
          {
            "type": "MUTATE_FACT",
            "parameters": { "targetVar": "paymentAmount", "operator": "SUB", "method": "PERCENTAGE", "operand": 10 }
          }
        ]
      }
    ],
    "decisionTraces": [
      {
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% Discount",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "status": "SELECTED",
        "reasonCode": "FINAL_WINNER",
        "reasonDetail": null
      }
    ]
  }
}

data.traceId is the execution’s audit handle — store it alongside your own records to trace this execution later. The data object exposes three layers of state explicitly:

inputFacts — facts as received from the request, normalized.
mutatedFacts — only the facts whose values were changed by rule actions.
generatedVariables — variables created by rule actions that did not exist in the input. Includes per-action change keys: {targetVar}__delta carries the signed change applied by MUTATE_FACT.

This split makes audits, replays, and debugging deterministic — you always know which value originated where. The merged “final state” can be reconstructed as { ...inputFacts, ...mutatedFacts, ...generatedVariables }.

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. The replay is a normal 200 — not an error. It carries the same traceId and the same executedAt as the first call, which is how you can tell a replay from a fresh execution. I-001 below is a different situation: the key is spent and this request could not be served from it. Key format. Up to 255 characters. How you generate keys is up to you; we suggest a V4 UUID or another random string with enough entropy to avoid collisions. A longer key is rejected with I-003 rather than truncated, because truncation would fold two distinct keys into one and serve one request as a replay of another. Keys are stored in plaintext on the execution ledger and kept for the retention period, so do not put personal data in them — no email addresses, phone numbers, or names.

Specific Version Execution

Executes a specific version of a policy group, bypassing traffic routing. Use it to run one version on requests you send yourself, for example a rollback target before you roll back to it, or an A/B test’s test version.

POST /groups/{groupId}/versions/{versionId}

The request and response formats are the same as for Single Group Execution, and the call is billed and recorded in execution history the same way. Apart from which version runs, it differs from Single Group Execution in two ways:

It does not use the compiled-rule cache. Each call loads the version and compiles it again, so every response time includes compilation.
Performance Profiling does not measure these calls, so they never appear in the Performance tab.

To split production traffic between versions, use an A/B test instead. Calls that an A/B test routes use the compiled-rule cache and are profiled.

Only versions that have been published can run this way. To test a DRAFT version, use Dry Run.

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": { "userId": "user_1", "paymentAmount": 50000 } },
      { "facts": { "userId": "user_2", "paymentAmount": 150000 } },
      { "facts": { "userId": "user_3", "paymentAmount": 300000 } }
    ],
    "sharedContext": {
      "channel": "batch-job"
    }
  }'

Field	Type	Required	Description
`requests`	array	✅	List of fact sets to evaluate
`sharedContext`	object		Context merged into every request

Response

{
  "result": "SUCCESS",
  "data": {
    "results": [
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "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": {
      "userId": "user_abc",
      "paymentAmount": 250000
    },
    "context": {
      "channel": "checkout"
    }
  }'

Field	Type	Required	Description
`targetGroupIds`	array	✅	Policy group IDs to evaluate
`facts`	object	✅	Shared input facts for all groups
`context`	object		Shared context for all groups

Response

The response contains merged inputFacts, mutatedFacts, generatedVariables, 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": "01f2b274-...",
    "versionId": "a6062090-...",
    "versionNo": 5,
    "requiredFacts": [
      {
        "key": "paymentAmount",
        "type": "NUMBER",
        "displayName": "Payment Amount",
        "usedBy": [
          "Condition [GREATER_THAN_OR_EQUAL] in rule: VIP 10% Discount",
          "MUTATE_FACT action in rule: VIP 10% Discount"
        ]
      },
      {
        "key": "customerTier",
        "type": "STRING",
        "displayName": "Customer Tier",
        "usedBy": [
          "Condition [EQUALS] in rule: VIP 10% Discount"
        ]
      }
    ],
    "exampleRequest": {
      "facts": { "paymentAmount": 50000, "customerTier": "" },
      "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.

Pre-registered Facts

Every tenant gets these pre-registered facts immediately after account creation. You do not need to create them manually:

Key	Type	Description
`userId`	STRING	User ID
`userTags`	LIST_STRING	User Tags
`isBlocked`	BOOLEAN	`true` when a `BLOCK` action ran
`blockReason`	STRING	The `reason` of the `BLOCK` action, or `Policy Violation` if it has none

isBlocked and blockReason are system facts that only BLOCK writes (see Fact Definitions). When a BLOCK action runs, they come back in generatedVariables. If your request sent them, they come back in mutatedFacts only when the value changes. To use a previous call’s block in a condition, send it under another key such as previouslyBlocked. Whether each fact is required for a particular execution depends on which rules in the deployed version reference it. Call GET /groups/{groupId}/requirements to see exactly which facts the engine expects. All other facts (e.g., paymentAmount, customerTier, orderRegion) are user-defined and must be registered via Fact Definitions before use.

Error Handling

All errors follow the same envelope shape:

{ "result": "ERROR", "errorCode": "P-001", "message": "Policy group not found." }

The most common errors you will encounter when calling execution endpoints:

HTTP	Code	When it happens
400	`C-001`	Request body malformed or fails validation
400	`I-003`	`Idempotency-Key` exceeds 255 characters. Shorten it and retry — the key is not truncated
400	`P-015`	Required input facts missing — call `/requirements` to check
400	`P-016`	(Specific Version mode) The version does not belong to the target group
400	`P-019`	Group has no deployed version yet — deploy a version first
400	`P-052`	An input value falls outside the fact’s declared value domain. Execution checks the copy taken when the version was published (details)
400	`P-060`	An input value’s type differs from the type declared for the fact, for example `"85"` for a NUMBER. Like `P-052`, execution reads the copy taken when the version was published
401	`A-003`	The `x-api-key` header is missing, malformed, or revoked
403	`B-008`	Monthly execution quota reached for the current plan
403	`P-009`	Group exists but is in `DISABLED` status
404	`P-001`	`groupId` does not exist or belongs to another tenant
404	`P-002`	(Specific Version mode) `versionId` does not exist
409	`I-001`	`Idempotency-Key` is already spent. Retrying does not clear it — use a new key. An identical replay does not reach here: it returns `200` with the original response
409	`I-002`	A request with this `Idempotency-Key` is currently in flight — retry shortly
429	`C-007`	Request rate exceeded plan’s Max TPS
500	`P-003`	Action execution raised an error during evaluation

For the complete code registry across all domains (auth, billing, simulation, etc.), see Error Reference.

Next Steps

Dry Run

Test rules without side effects before going live.

​Base URL

​Authentication

​Execution Modes

​Single Group Execution

​Request

​Response

​Idempotency

​Specific Version Execution

​Batch Execution

​Request

​Response

​Composite Execution

​Request

​Response

​Requirements

​Request

​Response

​Pre-registered Facts

​Error Handling

​Next Steps

Dry Run

Fact Definitions

Base URL

Authentication

Execution Modes

Single Group Execution

Request

Response

Idempotency

Specific Version Execution

Batch Execution

Request

Response

Composite Execution

Request

Response

Requirements

Request

Response

Pre-registered Facts

Error Handling

Next Steps