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}`	A/B testing, rollback testing
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. 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": { "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.

System Facts

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

Key	Type	Description
`userId`	STRING	User ID
`userTags`	LIST_STRING	User Tags

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
401	`A-003`	The `x-api-key` header is missing, malformed, or revoked
404	`P-001`	`groupId` does not exist or belongs to another tenant
403	`P-009`	Group exists but is in `DISABLED` status
400	`P-019`	Group has no deployed version yet — deploy a version first
404	`P-002`	(Specific Version mode) `versionId` does not exist
400	`P-016`	(Specific Version mode) The version does not belong to the target group
400	`P-015`	Required input facts missing — call `/requirements` to check
400	`C-001`	Request body malformed or fails validation
400	`P-003`	Action execution raised an error during evaluation
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
400	`I-003`	`Idempotency-Key` exceeds 255 characters. Shorten it and retry — the key is not truncated
403	`B-008`	Monthly execution quota reached for the current plan
429	`C-007`	Request rate exceeded plan’s Max TPS

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

​System 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

System Facts

Error Handling

Next Steps