> For the complete documentation index, see [llms.txt](https://docs.intelligems.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.intelligems.io/developer-resources/external-api/agentic-logic.md).

# Agentic Logic

## Agentic Logic

Manage recommendation rules, drafts, published versions, Sources, placements, assignments, and organization exclusions. Evaluate rules and saved scenarios before use.

Send your customer API key in the `intelligems-access-token` header. The key selects your organization. Do not send `orgId`. Agentic Logic must be enabled for that organization; a disabled organization receives 404.

Read and evaluate operations need the key's `read_experiments` scope. Operations that change rules, drafts, publish jobs, Sources, placements, assignments, or exclusions need `write_experiments`. A key without the scope receives 403.

Create a rule, save its draft, validate it, and publish it. Publish and run-gates requests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint until the job completes. A failed validation can return 200 with `valid: false`; check the response body before you publish.

All operations share a rate limit per API key: 50 requests initially, refilling 25 requests every 30 seconds. A rate-limited request returns 429. Use the `Retry-After` and `X-RateLimit-*` response headers to schedule retries.

## List assignments

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/assignments\
> \`\`\`\
> \
> Lists the organization's placement assignments.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/assignments":{"get":{"operationId":"listAgenticLogicPlacementAssignments","summary":"List assignments","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/assignments\n```\n\nLists the organization's placement assignments.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Assignment id (uuid)."},"placementId":{"type":"string","description":"Placement being filled (uuid)."},"ruleId":{"type":"string","description":"Rule that fills it (uuid)."},"variationId":{"description":"Experiment variation this assignment belongs to, or null for the org's global default. The global cell applies to EVERY variation unless that variation has an enabled cell of its own, which overrides it. Only the experience save writes a variation cell; the assignment verbs write global rows only.","type":["string","null"]},"experience":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"variationName":{"type":"string"},"category":{"type":"string","enum":["experiment","personalization"]},"status":{"type":"string","enum":["pending","started","ended","paused"]},"isDeleted":{"type":"boolean"}},"required":["id","name","variationName","category","status","isDeleted"],"additionalProperties":false},{"type":"null"}],"description":"The experience whose variation this assignment belongs to, resolved for display. Null on a global assignment, and also null when the variation no longer resolves — variationId is deliberately not a foreign key."},"budgetMs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":10000},{"type":"null"}],"description":"Per-assignment evaluation budget in milliseconds (maximum 10000ms), or null to use the runtime default. Publish gates check rules against the tightest budget across their enabled assignments."},"enabled":{"type":"boolean","description":"Per-assignment pause. False = the cell is skipped at serve time without touching the rule's lifecycle state — a disabled variation cell therefore falls back to the placement's global cell, and only serves nothing when the global cell is missing or disabled too."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","placementId","ruleId","variationId","experience","budgetMs","enabled","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One rule ↔ placement assignment — a cell of the (variation × placement) matrix. Carries which rule fills the cell; the evaluation budget belongs to the assignment and the empty-result policy to the rule. One rule can be assigned to many placements."}}},"required":["assignments"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Create an assignment

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/assignments\
> \`\`\`\
> \
> Binds a rule to a placement's global cell.\
> \
> \- \`placementId\` (string UUID, required) — Target placement.\
> \- \`ruleId\` (string UUID, required) — Rule to serve.\
> \- \`variationId\` (null, optional) — Only \`null\` or an omitted field is\
> &#x20; accepted. The global cell serves traffic outside any experiment and every\
> &#x20; variation that has no enabled cell of its own; variation cells come from\
> &#x20; saving the experience.\
> \- \`enabled\` (boolean, optional, default \`true\`) — An enabled assignment serves\
> &#x20; traffic.\
> \- \`budgetMs\` (integer, optional, 1–10000) — Per-evaluation time budget. Omit it\
> &#x20; to use the surface's cap; an explicit budget is still capped by the\
> &#x20; surface's limit.\
> \
> \- One global assignment per placement; a taken cell answers 409.\
> \- A code rule can only be assigned to a placement on one of its\
> &#x20; \`targetSurfaces\`; any other surface answers 409.\
> \- What the slot does when the rule returns nothing is one of the rule's\
> &#x20; settings, not the assignment's. Set it on the rule.\
> \- Enabling a code rule requires a published (active) version.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/assignments":{"post":{"operationId":"createAgenticLogicPlacementAssignment","summary":"Create an assignment","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/assignments\n```\n\nBinds a rule to a placement's global cell.\n\n- `placementId` (string UUID, required) — Target placement.\n- `ruleId` (string UUID, required) — Rule to serve.\n- `variationId` (null, optional) — Only `null` or an omitted field is\n  accepted. The global cell serves traffic outside any experiment and every\n  variation that has no enabled cell of its own; variation cells come from\n  saving the experience.\n- `enabled` (boolean, optional, default `true`) — An enabled assignment serves\n  traffic.\n- `budgetMs` (integer, optional, 1–10000) — Per-evaluation time budget. Omit it\n  to use the surface's cap; an explicit budget is still capped by the\n  surface's limit.\n\n- One global assignment per placement; a taken cell answers 409.\n- A code rule can only be assigned to a placement on one of its\n  `targetSurfaces`; any other surface answers 409.\n- What the slot does when the rule returns nothing is one of the rule's\n  settings, not the assignment's. Set it on the rule.\n- Enabling a code rule requires a published (active) version.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"placementId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Placement being filled (uuid)."},"variationId":{"description":"Must be null or omitted — this verb writes the GLOBAL cell only. A non-null variation is refused: variation cells are derived from the experience save, which owns which rule each variation serves.","type":"null"},"ruleId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Rule that fills it (uuid)."},"budgetMs":{"description":"Per-assignment evaluation budget in ms, up to 10000ms. Omit to use the placement surface's cap, which is what serving enforces.","type":"integer","minimum":1,"maximum":10000},"enabled":{"default":true,"description":"Per-assignment pause flag. Defaults to true.","type":"boolean"}},"required":["placementId","ruleId"],"description":"Assign a rule to a placement as the org's GLOBAL default — the cell with no variation, which serves every variation that has no enabled cell of its own. Variation cells are not writable here: they are derived from the experience save, which owns which rule each variation serves. See AgenticLogicPlacementAssignmentDtoDescriptions.variationId."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","description":"Assignment id (uuid)."},"placementId":{"type":"string","description":"Placement being filled (uuid)."},"ruleId":{"type":"string","description":"Rule that fills it (uuid)."},"variationId":{"description":"Experiment variation this assignment belongs to, or null for the org's global default. The global cell applies to EVERY variation unless that variation has an enabled cell of its own, which overrides it. Only the experience save writes a variation cell; the assignment verbs write global rows only.","type":["string","null"]},"experience":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"variationName":{"type":"string"},"category":{"type":"string","enum":["experiment","personalization"]},"status":{"type":"string","enum":["pending","started","ended","paused"]},"isDeleted":{"type":"boolean"}},"required":["id","name","variationName","category","status","isDeleted"],"additionalProperties":false},{"type":"null"}],"description":"The experience whose variation this assignment belongs to, resolved for display. Null on a global assignment, and also null when the variation no longer resolves — variationId is deliberately not a foreign key."},"budgetMs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":10000},{"type":"null"}],"description":"Per-assignment evaluation budget in milliseconds (maximum 10000ms), or null to use the runtime default. Publish gates check rules against the tightest budget across their enabled assignments."},"enabled":{"type":"boolean","description":"Per-assignment pause. False = the cell is skipped at serve time without touching the rule's lifecycle state — a disabled variation cell therefore falls back to the placement's global cell, and only serves nothing when the global cell is missing or disabled too."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","placementId","ruleId","variationId","experience","budgetMs","enabled","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One rule ↔ placement assignment — a cell of the (variation × placement) matrix. Carries which rule fills the cell; the evaluation budget belongs to the assignment and the empty-result policy to the rule. One rule can be assigned to many placements."}},"required":["assignment"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Delete an assignment

> \`\`\`http\
> DELETE /v25-10-beta/agentic-logic/assignments/{assignmentId}\
> \`\`\`\
> \
> Deletes an assignment. The slot stops serving that rule immediately.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/assignments/{assignmentId}":{"delete":{"operationId":"deleteAgenticLogicPlacementAssignment","summary":"Delete an assignment","tags":["Agentic Logic"],"description":"```http\nDELETE /v25-10-beta/agentic-logic/assignments/{assignmentId}\n```\n\nDeletes an assignment. The slot stops serving that rule immediately.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"assignmentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Update an assignment

> \`\`\`http\
> PATCH /v25-10-beta/agentic-logic/assignments/{assignmentId}\
> \`\`\`\
> \
> Updates an assignment (rule, enable/disable, budget).\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/assignments/{assignmentId}":{"patch":{"operationId":"updateAgenticLogicPlacementAssignment","summary":"Update an assignment","tags":["Agentic Logic"],"description":"```http\nPATCH /v25-10-beta/agentic-logic/assignments/{assignmentId}\n```\n\nUpdates an assignment (rule, enable/disable, budget).\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"assignmentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ruleId":{"description":"Rule the existing assignment cell should serve. Repointing keeps the placement, variation, and serving settings intact.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"budgetMs":{"description":"New per-assignment budget in ms, up to 10000ms, or null to return to the placement surface's cap.","anyOf":[{"type":"integer","minimum":1,"maximum":10000},{"type":"null"}]},"enabled":{"description":"Per-assignment pause flag.","type":"boolean"}},"description":"Update the rule or serving config for one (placement, variation) assignment cell."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","description":"Assignment id (uuid)."},"placementId":{"type":"string","description":"Placement being filled (uuid)."},"ruleId":{"type":"string","description":"Rule that fills it (uuid)."},"variationId":{"description":"Experiment variation this assignment belongs to, or null for the org's global default. The global cell applies to EVERY variation unless that variation has an enabled cell of its own, which overrides it. Only the experience save writes a variation cell; the assignment verbs write global rows only.","type":["string","null"]},"experience":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"variationName":{"type":"string"},"category":{"type":"string","enum":["experiment","personalization"]},"status":{"type":"string","enum":["pending","started","ended","paused"]},"isDeleted":{"type":"boolean"}},"required":["id","name","variationName","category","status","isDeleted"],"additionalProperties":false},{"type":"null"}],"description":"The experience whose variation this assignment belongs to, resolved for display. Null on a global assignment, and also null when the variation no longer resolves — variationId is deliberately not a foreign key."},"budgetMs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":10000},{"type":"null"}],"description":"Per-assignment evaluation budget in milliseconds (maximum 10000ms), or null to use the runtime default. Publish gates check rules against the tightest budget across their enabled assignments."},"enabled":{"type":"boolean","description":"Per-assignment pause. False = the cell is skipped at serve time without touching the rule's lifecycle state — a disabled variation cell therefore falls back to the placement's global cell, and only serves nothing when the global cell is missing or disabled too."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","placementId","ruleId","variationId","experience","budgetMs","enabled","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One rule ↔ placement assignment — a cell of the (variation × placement) matrix. Carries which rule fills the cell; the evaluation budget belongs to the assignment and the empty-result policy to the rule. One rule can be assigned to many placements."}},"required":["assignment"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Evaluate

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/evaluate\
> \`\`\`\
> \
> Evaluates the active rule assigned to a placement without changing rule or\
> placement state. It returns evaluation\
> telemetry, and does not record an impression.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/evaluate":{"post":{"operationId":"evaluateAgenticLogicRule","summary":"Evaluate","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/evaluate\n```\n\nEvaluates the active rule assigned to a placement without changing rule or\nplacement state. It returns evaluation\ntelemetry, and does not record an impression.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request":{"type":"object","properties":{"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the recommendation will render on. There is deliberately no 'headless' value — API callers declare the surface they render."},"placementId":{"type":"string","description":"Identifier of the placement being filled."},"cart":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"ISO-4217 currency code the shopper pays in. Every money field in this cart is in it except `shopSubtotal`."},"subtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart merchandise subtotal in integer minor units of `currency`, before shipping and taxes. Do not compare it against a money threshold: thresholds are in the store's currency, so use `shopSubtotal ?? subtotal`."},"shopSubtotal":{"description":"The same subtotal converted to the store's default currency, in integer minor units of that currency. Money thresholds compare against this, so a $50 threshold means $50 whatever the shopper pays in. Equal to `subtotal` when the cart is already in the store's currency. null when the store's currency or the cart currency's exchange rate is not known yet, so no threshold can match. Absent when serving did not compute it (scenario and test carts), so read `shopSubtotal ?? subtotal`.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total unit quantity across all lines (sum of line quantities) — units, not the count of distinct lines."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line in the visitor's current cart."},"description":"The cart lines."}},"required":["currency","subtotal","itemCount","lines"],"description":"Snapshot of the visitor's current cart. An empty cart (zero lines) is a legal cart — distinct from cart: null, which means the surface has no cart at all (post-purchase)."},{"type":"null"}],"description":"Current cart, or null when the surface has no cart (post-purchase). An empty cart is legal onsite — branch on surface, not on cart == null."},"order":{"anyOf":[{"type":"object","properties":{"orderId":{"type":"string","description":"Shopify order GID (gid://shopify/Order/<n>)."},"checkoutToken":{"description":"Shopify checkout token for the checkout that produced this order, when available.","type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Order creation time as an ISO-8601 UTC timestamp."},"currencyCode":{"type":"string","description":"ISO-4217 shop currency code the order's money fields are denominated in."},"presentmentCurrency":{"type":"string","description":"ISO-4217 currency code the shopper saw at checkout, which may differ from `currencyCode`."},"itemsSubtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Merchandise subtotal after line-level discounts but before order-level discounts, shipping, and taxes. Integer minor units."},"discountTotal":{"description":"Total order-level discount amount in integer minor units, when any.","type":"integer","minimum":0,"maximum":9007199254740991},"shippingTotal":{"description":"Shipping charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"taxTotal":{"description":"Taxes charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"What the shopper was actually charged, in integer minor units."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}},"title":{"description":"Product title at purchase time, when available.","type":"string"},"vendor":{"description":"Product vendor at purchase time, when available.","type":"string"},"productType":{"description":"Shopify product type at purchase time, when available.","type":"string"},"sellingPlanId":{"description":"Shopify selling-plan GID (gid://shopify/SellingPlan/<n>) when the line was purchased on a subscription.","type":"string"},"discountAllocations":{"description":"Line-level discount allocations applied to this line, when any.","type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Discount amount allocated to the line, in integer minor units of the order's currency."},"title":{"description":"Discount title or code as shown on the order, when available.","type":"string"}},"required":["amount"],"description":"One discount amount allocated to an order line."}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line on the completed order. Extends the cart-line shape with catalog metadata that is available once the order exists."},"description":"The purchased order lines."}},"required":["orderId","createdAt","currencyCode","presentmentCurrency","itemsSubtotal","total","lines"],"description":"The completed order a post-purchase surface is rendered against. First-class on the post-purchase surface only; null everywhere else. Deliberately carries NO customer field — the top-level request `customer` is the single customer reference."},{"type":"null"}],"description":"Completed order — first-class on the post-purchase surface only; null elsewhere."},"pageProduct":{"anyOf":[{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID of the product being viewed (gid://shopify/Product/<n>). The bare numeric id the Shopify admin shows is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"handle":{"type":"string","description":"Shopify product handle (URL slug) of the product being viewed."},"targeting":{"description":"Theme product facts used for onsite product targeting. Null when the theme has no product data; product-targeted branches then do not match. Absent from clients that predate the field; serving then reads the facts from Shopify when the rule targets the product.","anyOf":[{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}},"inventory":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lowestVariantPrice":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tags","collectionIds","inventory","lowestVariantPrice"]},{"type":"null"}]}},"required":["productId","handle"],"description":"The product a PDP placement is rendered on. Populated for onsite product-page placements only; null everywhere else."},{"type":"null"}],"description":"Product the placement's page is about — onsite PDP placements only; null everywhere else."},"customer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Shopify customer GID (gid://shopify/Customer/<n>)."},"ordersCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Number of orders this customer has placed, or null when the surface did not supply it — checkout supplies it for a verified buyer when the app's protected-customer-data grant covers it; onsite and post-purchase never do. Integer, >= 0, when present. Null-check it, or use sdk.getCustomer() for a count that does not depend on the grant."},"amountSpent":{"description":"Lifetime spend aggregate, when known.","type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Lifetime amount spent in integer minor units of `currency`."},"currency":{"type":"string","description":"ISO-4217 currency code `amount` is denominated in."}},"required":["amount","currency"]}},"required":["id","ordersCount"],"description":"Minimal identified-customer context, or null for guests. PII-MINIMAL GUARANTEE: this object carries ids, counts, and money aggregates ONLY — no email, name, phone, or address field may ever be added here. That is a contract property, not a data-availability accident; richer profile data is fetched at rule runtime via sdk.getCustomer()."},{"type":"null"}],"description":"Identified customer, or null for guests."},"shipping":{"type":"object","properties":{"state":{"type":"string","enum":["resolved","assumed","not-applicable","unavailable"],"description":"'resolved' = thresholds are known facts for this visitor; 'assumed' = best-effort defaults that may be wrong, so treat them as a hint rather than a fact when steering; 'not-applicable' = the store has no shipping incentive here, and the order may not be shipping at all; 'unavailable' = the shipping facts could not be read before the serving deadline (a Shopify read failed or timed out), so no threshold field is present and nothing is known — never read it as 'no incentive'."},"currency":{"type":"string","description":"ISO-4217 currency code the threshold fields are denominated in. Always present, even when state is 'not-applicable'."},"freeShippingThreshold":{"description":"Cart subtotal at which shipping becomes free, in integer minor units — pre-resolved to the visitor's assigned variation's threshold. Absent when there is no free-shipping incentive.","type":"integer","minimum":0,"maximum":9007199254740991},"remainingToFreeShipping":{"description":"How much more the visitor must add to qualify for free shipping, in integer minor units. 0 = already qualifies; absent or null = unresolvable.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"tiers":{"description":"Tiered incentive ladder in ascending threshold order, when the store runs tiered incentives.","type":"array","items":{"type":"object","properties":{"threshold":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart subtotal at which this tier unlocks, in integer minor units of the shipping context's currency."},"label":{"type":"string","description":"Shopper-facing label for the tier (e.g. 'Free shipping')."}},"required":["threshold","label"],"description":"One rung of a tiered shipping-incentive ladder."}},"delivery":{"description":"The delivery options Shopify computed for this checkout, as observed facts rather than merchant settings. Present only at checkout, and only once Shopify has computed options (an address or a pickup selection exists); absent onsite, post-purchase, and on first render. Present under every state, including 'not-applicable' for local pickup.","type":"object","properties":{"isLocalPickup":{"type":"boolean","description":"True when every selected delivery option is a pickup option — the buyer is not shipping anything."},"selected":{"description":"The buyer's currently selected option, when exactly one delivery group has a selection. Absent before the buyer picks, and when multiple groups (a subscription plus a one-time purchase) select different options — read `options` then.","type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"]},"options":{"type":"array","items":{"type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"],"description":"One delivery option Shopify offered the buyer at checkout — a shipping rate or a pickup choice — in the rule envelope's minor-unit money convention. PII-MINIMAL: option facts only, never the destination."},"description":"Every option Shopify computed, flattened across delivery groups, in Shopify's order. A zero-cost non-pickup option means the buyer already qualifies for free shipping."}},"required":["isLocalPickup","options"]}},"required":["state","currency"],"description":"Shipping-incentive context. Required — 'not-applicable' is expressed in-band via its state field, never by omitting the object."},"country":{"description":"OPTIONAL. ISO-3166-1 alpha-2 code of the market this request should be evaluated in, e.g. 'CA'. Omit it (or send null) and the platform evaluates in its default market, 'US'. Name it whenever the cart is denominated in a non-shop currency, so the catalog reads run in the same market the money does.","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"cartFingerprint":{"description":"Opaque client-supplied fingerprint of the cart state this request was built from. The engine echoes it verbatim on the result envelope so the rendering surface can compare and discard late results.","type":"string"}},"required":["surface","placementId","cart","order","pageProduct","customer","shipping"],"description":"The full serving request envelope. `placementId` must be an API-created placement with an enabled assignment; `surface` declares the surface your rendering context corresponds to."},"slotsNeeded":{"type":"integer","minimum":0,"maximum":50,"description":"How many recommendation slots the caller intends to render. Non-negative integer, at most 50. Zero is legal and asks the rule for an empty result; it is not an error."},"visitorId":{"description":"Seed for the deterministic shuffle (with the rule version). Omitted = a fresh random id per call. Pass a fixed value to make repeat calls comparable against pinned fixtures; live results still drift with the catalog.","type":"string","minLength":1,"maxLength":128},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country the evaluation should price and read Storefront data for."},"variationId":{"description":"Experiment cell to resolve the assignment in. Null or omitted = the placement's global cell. A named variation resolves its own enabled cell when it has one, and otherwise falls back to the global cell — a disabled variation cell does not suppress the global default.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["request","slotsNeeded","country"],"description":"Run one evaluation against a supplied request context and return the versioned result envelope. Metered per organization; never recorded as an impression. The result never holds more than the slot count and already reflects the rule's exclusion settings, out of stock included."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"envelope":{"type":"object","properties":{"version":{"type":"number","const":1,"description":"Envelope schema version. Activating any reserved shape bumps this version — consumers negotiate on it, it never breaks silently. Independent of the REST API path version."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["product","variant","image","reviewRef","metaobjectRef","bundle"],"description":"Item kind. Consumers ignore kinds they don't understand — never errors."},"id":{"type":"string","description":"Shopify GID of the recommended entity, scoped by `kind` (e.g. gid://shopify/Product/<n> for kind 'product'). For kind 'bundle' the id is the Product GID of the bundle's parent/anchor product, never a merchant-chosen key — there is no gid://shopify/Bundle/<n>."},"defaultVariantId":{"description":"Which variant is pre-selected for the shopper — the core output for product-kind items, so surfaces render a purchasable default without re-deriving one.","type":"string"},"allowedVariantIds":{"description":"Exhaustive list of variant GIDs the shopper may add, when the merchant restricted the item to a subset of its variants. ABSENT means unrestricted (every variant is allowed); present means only these are. Surfaces that mint per-variant discount signatures MUST sign only these — treating absence and an empty list alike would mint a signature for a variant the merchant excluded.","type":"array","items":{"type":"string"}},"sellingPlanId":{"description":"Shopify selling-plan GID to attach when the item is added, for subscription recommendations. RESERVED in V1.","type":"string"},"intent":{"description":"'add' adds the item to the cart. 'replace' asks the surface to swap out the originating cart line and is materialized by NO surface today — emitting it is refused at publish rather than silently downgraded, because a surface that can only Add would put the swap target alongside the item it was meant to replace. Recommend the swap target with intent 'add', or wait for a surface that supports it. RESERVED in V1.","type":"string","enum":["add","replace"]},"discount":{"description":"RESERVED in V1 and read by NO surface — setting it prices nothing, and it is REFUSED at ingress. Pricing is the placement's, never the rule's. Activating this field bumps the envelope version.","type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"],"description":"'percentage' or 'fixed'."},"value":{"type":"number","minimum":0,"description":"For 'percentage': percent points (10 = 10% off). For 'fixed': integer minor units in the shop currency."}},"required":["type","value"],"additionalProperties":false},"sourceBranch":{"description":"Path-capable label of the rule branch that produced this item (e.g. 'colour-match/size-in-stock'), for telemetry and debugging.","type":"string"},"children":{"description":"Child lines when kind is 'bundle'. Each child's `id` must match its own `kind` — a 'product' child carries a Product GID, a 'variant' child a ProductVariant GID. Schema-level tolerance: presence on other kinds is a gate concern, not a parse error.","type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["product","variant","image","reviewRef","metaobjectRef","bundle"],"description":"Kind of the child item (scopes how `id` is interpreted)."},"id":{"type":"string","description":"Shopify GID of the child, scoped by `kind`."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Units of the child included in the bundle. Positive integer."}},"required":["kind","id","quantity"],"additionalProperties":false,"description":"One child line of a bundle-kind recommendation item."}}},"required":["kind","id"],"additionalProperties":false,"description":"One recommended item. `kind` scopes how `id` is interpreted. Consumers MUST ignore kinds they do not understand — unknown kinds are never errors; the kind list exists so gates can validate rule output, not so surfaces can reject envelopes."},"description":"Recommended items in render order. An empty array is a valid result — a miss, not an error."},"branchFired":{"description":"The terminal rule branch that produced this result.","type":"object","properties":{"base":{"type":"string","description":"The literal label passed to attempt('label') in the rule source — statically lexable, so publish gates can verify it exists in the code."},"instance":{"description":"Runtime instance qualifier when one branch runs multiple passes (e.g. the tag this pass ran against). Present ONLY when the attempt supplied one via `attempt(base, fn, { instance })`; the key is omitted entirely otherwise, so consumers must treat its absence as normal and must never assert deep equality against an object that assumes it.","type":"string"}},"required":["base"],"additionalProperties":false},"cartFingerprint":{"description":"Echo of the request's cartFingerprint, verbatim. The rendering surface compares it against the current cart state and discards late results that no longer match.","type":"string"},"warnings":{"description":"Non-fatal notices from the evaluation, surfaced to telemetry and debugging tools.","type":"array","items":{"type":"string"}},"metadata":{"description":"Rule-authored metadata. Free-form and read by NOTHING — no key here is interpreted. A rule decides WHICH products are recommended; it never prices them. The discount and the struck-through price belong to the placement the rule is attached to, where the merchant sets them.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["version","items"],"additionalProperties":false,"description":"What a recommendation rule returns. Conventions: ids are Shopify GIDs; money is integer minor units with explicit ISO-4217 currency; timestamps are ISO-8601 UTC. Engine errors and timeouts collapse to an empty result behaviorally (the surface follows the placement's onEmpty policy) but stay distinct in evaluation telemetry."},"telemetry":{"type":"object","properties":{"outcome":{"type":"string","enum":["result","empty","error"],"description":"'result' = items returned; 'empty' = valid miss (zero items); 'error' = the evaluation failed or timed out and the surface fell back to empty behavior."},"errorClass":{"description":"Free-form classifier of the failure when outcome is 'error'. Deliberately not an enum yet — the vocabulary gets pinned once real failure modes exist.","type":"string"},"datasetRevisions":{"description":"The dataset revisions the evaluation's pinned reads resolved to, one entry per distinct key read. This is the field the impression stamp records (persistence lands with the impression store, M4).","type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The dataset key the evaluation read."},"revision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The revision the evaluation's pinned read resolved to."}},"required":["key","revision"],"additionalProperties":false,"description":"One resolved dataset pin of an evaluation: the key and the exact revision the evaluation read."}},"removedByExclusion":{"description":"Items removed by serving exclusions, with only the item id and the approved removal reason.","type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"reason":{"type":"string","enum":["product_id","tag","collection","vendor","metadata_unavailable"]}},"required":["itemId","reason"],"additionalProperties":false}},"attempts":{"description":"Per-attempt chain records in execution order, captured by the SDK runtime's accumulator — never authored by rule code. Fallback rate = attempt 1 contributed 0. Absent means no chain ran, never 'zero attempts'.","type":"array","items":{"type":"object","properties":{"base":{"type":"string","description":"The attempt's stable base label (e.g. 'colour-match')."},"instance":{"description":"Per-invocation instance qualifier (e.g. the seed product handle) for readout grouping. Present ONLY when the attempt supplied one via `attempt(base, fn, { instance })`; the key is omitted entirely otherwise, so consumers must treat its absence as normal and must never assert deep equality against a record that assumes it.","type":"string"},"contributed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of this attempt's items made the final result. Non-negative integer."},"outcome":{"type":"string","enum":["contributed","empty","not-selected","skipped","error"],"description":"'contributed' | 'empty' | 'not-selected' | 'skipped' | 'error' — see AgenticLogicAttemptOutcomeList for exact semantics."}},"required":["base","contributed","outcome"],"additionalProperties":false,"description":"Telemetry record for one chain attempt. Chains emit one per attempt so readouts can show exactly which branches ran, contributed, or fell through."}},"evaluationSource":{"description":"Which lane produced this evaluation: 'serving' = a shopper-facing surface, 'api' = the metered external/MCP evaluate endpoint, 'preview' = authoring preview, 'eligibility' = a server-side check on a cart no shopper sees. 'api', 'preview' and 'eligibility' evaluations are never impressions — readouts must exclude them.","type":"string","enum":["serving","api","preview","eligibility"]},"executionTier":{"description":"Which executor ran the rule: 'template' = the shared warm template runner, 'custom' = the org's own rule Lambda. Absent when the evaluation exited before an assignment resolved, so nothing ran. Not the same vocabulary as the stored version execution kind.","type":"string","enum":["template","custom"]},"deadlineMs":{"description":"The RELATIVE time budget the evaluation ran under, in milliseconds — min(surface hard cap, the assignment's budgetMs). The absolute epoch deadline is meaningless in a readout and already rides the invocation as system.deadlineAtMs. Absent when the evaluation exited before an assignment resolved.","type":"integer","minimum":0,"maximum":9007199254740991},"fallback":{"description":"What the placement's onEmpty policy did with an empty rule result: 'not-applicable' = the rule returned items, so no policy ran; 'hidden' = onEmpty is 'hide'; 'materialized' = the smart-recs fallback supplied the items; 'unavailable' = smart-recs was asked and had nothing to give; 'failed' = the fallback read itself errored. This is what separates empties a readout would otherwise collapse into one bucket.","type":"string","enum":["not-applicable","hidden","materialized","unavailable","failed"]},"classifierBreakerTripped":{"description":"Whether the org-scoped storefront-classifier breaker was already open when this evaluation started, so the rule was short-circuited rather than executed. Absent when the evaluation exited before the breaker was consulted.","type":"boolean"}},"required":["outcome"],"additionalProperties":false,"description":"Telemetry facts for one rule evaluation. Emission is the broker's job; the shape is typed here so the vocabulary is pinned with the envelope. Errors and timeouts collapse to empty behaviorally (the surface follows the placement's onEmpty policy) but stay distinct here."}},"required":["envelope","telemetry"],"additionalProperties":false,"description":"The versioned result envelope and evaluation telemetry. `telemetry.evaluationSource` is 'api' on this endpoint."}},"required":["result"],"additionalProperties":false,"description":"The evaluation result: the versioned envelope plus its telemetry facts."}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Get exclusions

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/exclusions\
> \`\`\`\
> \
> Returns the organization's exclusion set as \`{ exclusions }\`. Use the \`intelligems-access-token\` header.\
> \
> \- \`productIds\` (string array) — Shopify product GIDs.\
> \- \`tags\` (string array) — Exact product tags.\
> \- \`collections\` (string array) — Shopify collection GIDs; their members are\
> &#x20; excluded.\
> \- \`vendors\` (string array) — Exact vendor names.\
> \- \`lastUpdateTs\` (number or null) — Last edit time in Unix epoch milliseconds;\
> &#x20; \`null\` when the organization has never saved exclusions, in which case\
> &#x20; every list is empty.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/exclusions":{"get":{"operationId":"getAgenticLogicOrgExclusions","summary":"Get exclusions","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/exclusions\n```\n\nReturns the organization's exclusion set as `{ exclusions }`. Use the `intelligems-access-token` header.\n\n- `productIds` (string array) — Shopify product GIDs.\n- `tags` (string array) — Exact product tags.\n- `collections` (string array) — Shopify collection GIDs; their members are\n  excluded.\n- `vendors` (string array) — Exact vendor names.\n- `lastUpdateTs` (number or null) — Last edit time in Unix epoch milliseconds;\n  `null` when the organization has never saved exclusions, in which case\n  every list is empty.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"exclusions":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string"},"description":"Products never to recommend (gid://shopify/Product/<n>)."},"tags":{"type":"array","items":{"type":"string"},"description":"Product tags never to recommend."},"collections":{"type":"array","items":{"type":"string"},"description":"Collections whose members are never recommended (gid://shopify/Collection/<n>)."},"vendors":{"type":"array","items":{"type":"string"},"description":"Vendors whose products are never recommended."},"lastUpdateTs":{"description":"Last edit time, Unix epoch-ms; null when the org has never saved exclusions.","type":["number","null"]}},"required":["productIds","tags","collections","vendors","lastUpdateTs"],"additionalProperties":false,"description":"The org's serve-time ban list, enforced by the broker on every result envelope. One row per org; edits are effective immediately (no republish). All ids are Shopify GIDs."}},"required":["exclusions"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Update exclusions

> \`\`\`http\
> PATCH /v25-10-beta/agentic-logic/exclusions\
> \`\`\`\
> \
> Adds and removes selected organization-wide exclusions. The operation preserves\
> all values that the request does not name and returns the complete updated\
> exclusion set.\
> \
> \- \`add\` (object, optional) — Exclusion values to add.\
> \- \`remove\` (object, optional) — Exclusion values to remove.\
> \- \`add.productIds\` / \`remove.productIds\` (string array, optional) — Shopify\
> &#x20; product GIDs.\
> \- \`add.tags\` / \`remove.tags\` (string array, optional) — Exact product tags.\
> \- \`add.collections\` / \`remove.collections\` (string array, optional) — Shopify\
> &#x20; collection GIDs.\
> \- \`add.vendors\` / \`remove.vendors\` (string array, optional) — Exact vendor\
> &#x20; names.\
> \
> The request must add or remove at least one value. A value cannot occur in both\
> operations for the same field.\
> \
> \- Adding an existing value and removing a missing value are successful no-ops.\
> \- The update is atomic and takes effect on the next evaluation for every rule.\
> \- No rule publish is required.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/exclusions":{"patch":{"operationId":"patchAgenticLogicOrgExclusions","summary":"Update exclusions","tags":["Agentic Logic"],"description":"```http\nPATCH /v25-10-beta/agentic-logic/exclusions\n```\n\nAdds and removes selected organization-wide exclusions. The operation preserves\nall values that the request does not name and returns the complete updated\nexclusion set.\n\n- `add` (object, optional) — Exclusion values to add.\n- `remove` (object, optional) — Exclusion values to remove.\n- `add.productIds` / `remove.productIds` (string array, optional) — Shopify\n  product GIDs.\n- `add.tags` / `remove.tags` (string array, optional) — Exact product tags.\n- `add.collections` / `remove.collections` (string array, optional) — Shopify\n  collection GIDs.\n- `add.vendors` / `remove.vendors` (string array, optional) — Exact vendor\n  names.\n\nThe request must add or remove at least one value. A value cannot occur in both\noperations for the same field.\n\n- Adding an existing value and removing a missing value are successful no-ops.\n- The update is atomic and takes effect on the next evaluation for every rule.\n- No rule publish is required.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"description":"Exclusion values to add. Existing values are unchanged.","type":"object","properties":{"productIds":{"description":"Products never to recommend (gid://shopify/Product/<n>).","type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags never to recommend.","type":"array","items":{"type":"string","minLength":1}},"collections":{"description":"Collections whose members are never recommended (gid://shopify/Collection/<n>).","type":"array","items":{"type":"string","minLength":1}},"vendors":{"description":"Vendors whose products are never recommended.","type":"array","items":{"type":"string","minLength":1}}}},"remove":{"description":"Exclusion values to remove. Missing values are unchanged.","type":"object","properties":{"productIds":{"description":"Products never to recommend (gid://shopify/Product/<n>).","type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags never to recommend.","type":"array","items":{"type":"string","minLength":1}},"collections":{"description":"Collections whose members are never recommended (gid://shopify/Collection/<n>).","type":"array","items":{"type":"string","minLength":1}},"vendors":{"description":"Vendors whose products are never recommended.","type":"array","items":{"type":"string","minLength":1}}}}},"description":"Add or remove selected org exclusions without replacing unrelated values. Effective immediately on the next evaluation; no republish."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"exclusions":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string"},"description":"Products never to recommend (gid://shopify/Product/<n>)."},"tags":{"type":"array","items":{"type":"string"},"description":"Product tags never to recommend."},"collections":{"type":"array","items":{"type":"string"},"description":"Collections whose members are never recommended (gid://shopify/Collection/<n>)."},"vendors":{"type":"array","items":{"type":"string"},"description":"Vendors whose products are never recommended."},"lastUpdateTs":{"description":"Last edit time, Unix epoch-ms; null when the org has never saved exclusions.","type":["number","null"]}},"required":["productIds","tags","collections","vendors","lastUpdateTs"],"additionalProperties":false,"description":"The org's serve-time ban list, enforced by the broker on every result envelope. One row per org; edits are effective immediately (no republish). All ids are Shopify GIDs."}},"required":["exclusions"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## List placements

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/placements\
> \`\`\`\
> \
> Lists the organization's placements.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/placements":{"get":{"operationId":"listAgenticLogicPlacements","summary":"List placements","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/placements\n```\n\nLists the organization's placements.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"placements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued placement id (uuid). Wire identity — never renamed or reused."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing placement name."},"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the placement renders on ('onsite' | 'checkout' | 'post-purchase'). Fixed at creation — a new surface is a new placement."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."},"lastSeenAtTs":{"description":"Liveness: when a real shopper request for this placement last reached the engine (Unix epoch-ms), or null if none has within the retention window. Only the `serving` lane beats it — previews and API evaluations never do — so it answers 'is this placement actually live on the storefront', not 'did it render products'. Best-effort and TTL-bounded; never a billing or analytics source.","type":["number","null"]}},"required":["id","organizationId","name","surface","createdAtTs","lastUpdateTs","lastSeenAtTs"],"additionalProperties":false,"description":"One placement: a server-issued addressable location a surface renders recommendations into. The placement's id IS the `placementId` requests and impressions carry."}}},"required":["placements"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Create a placement

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/placements\
> \`\`\`\
> \
> Creates a placement — a named slot on a surface that rules serve into.\
> \
> \- \`name\` (string, required) — Merchant-facing placement name.\
> \- \`surface\` (string, required) — \`onsite\`, \`checkout\`, or \`post-purchase\`.\
> &#x20; Fixed at creation.\
> \
> The returned \`placement.id\` is the \`placementId\` used by evaluation requests.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/placements":{"post":{"operationId":"createAgenticLogicPlacement","summary":"Create a placement","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/placements\n```\n\nCreates a placement — a named slot on a surface that rules serve into.\n\n- `name` (string, required) — Merchant-facing placement name.\n- `surface` (string, required) — `onsite`, `checkout`, or `post-purchase`.\n  Fixed at creation.\n\nThe returned `placement.id` is the `placementId` used by evaluation requests.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Merchant-facing placement name."},"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the placement renders on. Fixed at creation."}},"required":["name","surface"],"description":"Create a placement. The response's server-issued id is the wire `placementId`."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued placement id (uuid). Wire identity — never renamed or reused."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing placement name."},"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the placement renders on ('onsite' | 'checkout' | 'post-purchase'). Fixed at creation — a new surface is a new placement."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."},"lastSeenAtTs":{"description":"Liveness: when a real shopper request for this placement last reached the engine (Unix epoch-ms), or null if none has within the retention window. Only the `serving` lane beats it — previews and API evaluations never do — so it answers 'is this placement actually live on the storefront', not 'did it render products'. Best-effort and TTL-bounded; never a billing or analytics source.","type":["number","null"]}},"required":["id","organizationId","name","surface","createdAtTs","lastUpdateTs","lastSeenAtTs"],"additionalProperties":false,"description":"One placement: a server-issued addressable location a surface renders recommendations into. The placement's id IS the `placementId` requests and impressions carry."}},"required":["placement"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Delete a placement

> \`\`\`http\
> DELETE /v25-10-beta/agentic-logic/placements/{placementId}\
> \`\`\`\
> \
> Deletes a placement. A placement with any assignment answers 409; delete or\
> move its assignments first.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/placements/{placementId}":{"delete":{"operationId":"deleteAgenticLogicPlacement","summary":"Delete a placement","tags":["Agentic Logic"],"description":"```http\nDELETE /v25-10-beta/agentic-logic/placements/{placementId}\n```\n\nDeletes a placement. A placement with any assignment answers 409; delete or\nmove its assignments first.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"placementId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Rename a placement

> \`\`\`http\
> PATCH /v25-10-beta/agentic-logic/placements/{placementId}\
> \`\`\`\
> \
> Renames a placement. The id and surface never change.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/placements/{placementId}":{"patch":{"operationId":"updateAgenticLogicPlacement","summary":"Rename a placement","tags":["Agentic Logic"],"description":"```http\nPATCH /v25-10-beta/agentic-logic/placements/{placementId}\n```\n\nRenames a placement. The id and surface never change.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"placementId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New merchant-facing name."}},"description":"Edit a placement's name. The id and surface never change, and the empty-result policy belongs to the rule."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued placement id (uuid). Wire identity — never renamed or reused."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing placement name."},"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the placement renders on ('onsite' | 'checkout' | 'post-purchase'). Fixed at creation — a new surface is a new placement."},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."},"lastSeenAtTs":{"description":"Liveness: when a real shopper request for this placement last reached the engine (Unix epoch-ms), or null if none has within the retention window. Only the `serving` lane beats it — previews and API evaluations never do — so it answers 'is this placement actually live on the storefront', not 'did it render products'. Best-effort and TTL-bounded; never a billing or analytics source.","type":["number","null"]}},"required":["id","organizationId","name","surface","createdAtTs","lastUpdateTs","lastSeenAtTs"],"additionalProperties":false,"description":"One placement: a server-issued addressable location a surface renders recommendations into. The placement's id IS the `placementId` requests and impressions carry."}},"required":["placement"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## List rules

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules\
> \`\`\`\
> \
> Lists every Agentic Logic rule in the organization.\
> \
> \- Rules in every lifecycle state (\`draft\`, \`active\`, \`paused\`) are returned;\
> &#x20; filter client-side on \`state\`.\
> \- \`managedBy\` distinguishes builder-template rules (\`builder\`) from code rules\
> &#x20; (\`code\`).\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules":{"get":{"operationId":"listAgenticLogicRules","summary":"List rules","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules\n```\n\nLists every Agentic Logic rule in the organization.\n\n- Rules in every lifecycle state (`draft`, `active`, `paused`) are returned;\n  filter client-side on `state`.\n- `managedBy` distinguishes builder-template rules (`builder`) from code rules\n  (`code`).\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One recommendation rule: the org-scoped container that owns drafts, immutable versions, and placement assignments. The rule row carries lifecycle state; only 'active' rules are evaluable."}}},"required":["rules"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Create a rule

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules\
> \`\`\`\
> \
> Creates a rule in the \`draft\` state. The response is \`{ rule }\`.\
> \
> \- \`name\` (string, required) — Merchant-facing rule name.\
> \- \`description\` (string, required, 1–1024 characters) — Plain-language summary\
> &#x20; of what the rule recommends, in what order, and for which shoppers.\
> \- \`managedBy\` (string, required) — \`builder\` for a template-configured rule, or\
> &#x20; \`code\` for a rule whose source you author through the draft endpoint. Fixed\
> &#x20; after creation.\
> \- \`settings\` (object, optional) — Recommendation settings: \`maxItems\` (1–10),\
> &#x20; \`excludeOutOfStock\`, \`excludeItemsInCart\`, and \`onEmpty\` (\`hide\` or\
> &#x20; \`smart-recs\`), all required when the object is sent. Omit it to take the\
> &#x20; defaults: 3 items, both exclusions on, \`hide\`.\
> \
> A builder rule also takes:\
> \
> \- \`templateId\` (string, required) — Template to configure.\
> \- \`templateParams\` (object, optional) — Validated against the template's\
> &#x20; params schema.\
> \- \`templateVersion\` (number, optional) — Template version the params were\
> &#x20; written against.\
> \
> Builder rules don't take \`targetSurfaces\`; their template sets the surfaces.\
> \
> A code rule also takes:\
> \
> \- \`targetSurfaces\` (string array, required) — The surfaces (\`onsite\`,\
> &#x20; \`checkout\`, \`post-purchase\`) whose placements the rule may be assigned to.\
> &#x20; Non-empty, with no repeats, and fixed after creation.\
> \- \`authoringSessionId\` (string, optional) — The AI chat session authoring the\
> &#x20; rule.\
> \
> A code-rule body is strict: unknown fields are rejected.\
> \
> Creating a builder rule starts its first publish. A code rule needs a saved\
> draft before it can publish (see \[Save a code rule's draft]\(#save-a-code-rules-draft)).\
> A rule serves nothing until it has an active version and is assigned to a\
> placement.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules":{"post":{"operationId":"createAgenticLogicRule","summary":"Create a rule","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/rules\n```\n\nCreates a rule in the `draft` state. The response is `{ rule }`.\n\n- `name` (string, required) — Merchant-facing rule name.\n- `description` (string, required, 1–1024 characters) — Plain-language summary\n  of what the rule recommends, in what order, and for which shoppers.\n- `managedBy` (string, required) — `builder` for a template-configured rule, or\n  `code` for a rule whose source you author through the draft endpoint. Fixed\n  after creation.\n- `settings` (object, optional) — Recommendation settings: `maxItems` (1–10),\n  `excludeOutOfStock`, `excludeItemsInCart`, and `onEmpty` (`hide` or\n  `smart-recs`), all required when the object is sent. Omit it to take the\n  defaults: 3 items, both exclusions on, `hide`.\n\nA builder rule also takes:\n\n- `templateId` (string, required) — Template to configure.\n- `templateParams` (object, optional) — Validated against the template's\n  params schema.\n- `templateVersion` (number, optional) — Template version the params were\n  written against.\n\nBuilder rules don't take `targetSurfaces`; their template sets the surfaces.\n\nA code rule also takes:\n\n- `targetSurfaces` (string array, required) — The surfaces (`onsite`,\n  `checkout`, `post-purchase`) whose placements the rule may be assigned to.\n  Non-empty, with no repeats, and fixed after creation.\n- `authoringSessionId` (string, optional) — The AI chat session authoring the\n  rule.\n\nA code-rule body is strict: unknown fields are rejected.\n\nCreating a builder rule starts its first publish. A code rule needs a saved\ndraft before it can publish (see [Save a code rule's draft](#save-a-code-rules-draft)).\nA rule serves nothing until it has an active version and is assigned to a\nplacement.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"settings":{"description":"The rule's recommendation settings. Optional: omit to take the defaults (3 items, both exclusions on, hide when empty), which is what a merchant who never mentions them should get.","type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}}},"managedBy":{"type":"string","const":"builder","description":"'builder' or 'code'. Immutable after creation."},"templateId":{"type":"string","minLength":1,"description":"Template id for builder rules. Required when managedBy is 'builder'."},"templateParams":{"description":"Template params for builder rules, validated against the template's params schema at write time.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"templateVersion":{"description":"Template artifact version the params were authored against.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","description","managedBy","templateId"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"settings":{"description":"The rule's recommendation settings. Optional: omit to take the defaults (3 items, both exclusions on, hide when empty), which is what a merchant who never mentions them should get.","type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}}},"managedBy":{"type":"string","const":"code","description":"'builder' or 'code'. Immutable after creation."},"targetSurfaces":{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]},"description":"Surfaces this code rule is written for, and the only surfaces whose placements it may later be assigned to. Required for code rules, refused for builder rules, and immutable once set. Choose from the surfaces that can supply the request context the rule reads: post-purchase has an order and no cart, onsite has no customer identity, checkout has no page product."},"authoringSessionId":{"description":"Id of the AI chat session authoring this rule. Optional: a rule created outside a chat omits it. A later authoring session repoints it, so the workspace always loads back the conversation that explains the rule's current state.","type":"string","minLength":1}},"required":["name","description","managedBy","targetSurfaces"],"additionalProperties":false}],"description":"Create a rule container (state starts at 'draft').","type":"object"}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One recommendation rule: the org-scoped container that owns drafts, immutable versions, and placement assignments. The rule row carries lifecycle state; only 'active' rules are evaluable."}},"required":["rule"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Get a rule

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}\
> \`\`\`\
> \
> Gets one rule by id. The response is\
> \`{ rule, latestPublishJob, activeRepairRun }\`:\
> \
> \- \`latestPublishJob\` — The rule's most recent publish job (the same object\
> &#x20; \[Poll a publish job]\(#poll-a-publish-job) returns under \`job\`), or \`null\`\
> &#x20; when it has none.\
> \- \`activeRepairRun\` — The rule's AI repair run, live or most recently finished,\
> &#x20; or \`null\` when it never had one. It carries the run's status, attempt count,\
> &#x20; the job it is following, and why it stopped.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}":{"get":{"operationId":"getAgenticLogicRule","summary":"Get a rule","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}\n```\n\nGets one rule by id. The response is\n`{ rule, latestPublishJob, activeRepairRun }`:\n\n- `latestPublishJob` — The rule's most recent publish job (the same object\n  [Poll a publish job](#poll-a-publish-job) returns under `job`), or `null`\n  when it has none.\n- `activeRepairRun` — The rule's AI repair run, live or most recently finished,\n  or `null` when it never had one. It carries the run's status, attempt count,\n  the job it is following, and why it stopped.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One recommendation rule: the org-scoped container that owns drafts, immutable versions, and placement assignments. The rule row carries lifecycle state; only 'active' rules are evaluable."},"latestPublishJob":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Publish-job id (uuid) — the handle returned by the publish endpoint."},"ruleId":{"type":"string","description":"Rule the job publishes (uuid)."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"'queued' | 'running' | 'succeeded' | 'failed'."},"mode":{"type":"string","enum":["publish","dry_run"],"description":"'publish' (runs every gate and promotes a version on success) | 'dry_run' (validation gates only, never promotes). What the job IS — a reader cannot infer it from status while the job is still in flight."},"startedAtTs":{"description":"Worker start time, Unix epoch-ms; null while queued.","type":["number","null"]},"finishedAtTs":{"description":"Terminal time, Unix epoch-ms; null until the job finishes.","type":["number","null"]},"resultingVersionId":{"description":"Version the job promoted, when it succeeded in publish mode; null otherwise (and null again if that version is later deleted by retention).","type":["string","null"]},"gates":{"type":"array","items":{"type":"object","properties":{"gateKey":{"type":"string","enum":["static_contract","deps_locked","org_secrets_resolved","required_tests_passed","bundle_size","runtime_timeout","chain_cost","scan_cost","graph_consistency","ai_tests_generated","ai_tests_passed","user_tests_passed","lambda_deploy"],"description":"Which gate this result belongs to."},"status":{"type":"string","enum":["pending","running","passed","failed","warning","blocked"],"description":"'pending' | 'running' | 'passed' | 'failed' | 'warning' | 'blocked'. 'warning' passes with caveats; 'blocked' means an earlier gate's failure prevented this one from running."},"result":{"description":"Human-readable gate summary, when available.","type":["string","null"]},"detailsJson":{"description":"Structured gate details, when available.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"startedAtTs":{"description":"Gate start time, Unix epoch-ms, when started.","type":["number","null"]},"finishedAtTs":{"description":"Gate finish time, Unix epoch-ms, when finished.","type":["number","null"]}},"required":["gateKey","status"],"additionalProperties":false,"description":"One gate's result within a publish job. The gate-key vocabulary is owned by the publish-gate registry; the status vocabulary is identical to the custom-shipping-provider pipeline's so workers port cleanly."},"description":"Per-gate results, in pipeline order."}},"required":["id","ruleId","status","mode","startedAtTs","finishedAtTs","resultingVersionId","gates"],"additionalProperties":false,"description":"One publish job: the async unit that runs the gate pipeline against a frozen draft snapshot and, in publish mode, promotes a new active version on success."},{"type":"null"}]},"activeRepairRun":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"publishOnSuccess":{"type":"boolean"},"status":{"type":"string","enum":["queued","repairing","validating","converged","gave_up","abandoned","awaiting_approval"]},"purpose":{"type":"string","enum":["initial_publish"]},"attempt":{"type":"integer","minimum":0,"maximum":9007199254740991},"maxAttempts":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"currentPublishJobId":{"type":["string","null"]},"baselineDraftS3Key":{"type":["string","null"]},"giveUp":{"anyOf":[{"type":"object","properties":{"cause":{"type":"string","enum":["manual_publish","max_attempts","deadline","cost_budget","repair_unavailable","draft_changed","rule_fenced","stale","not_source_repairable","semantic_repair","cancelled"]},"blockingGate":{"type":["string","null"]},"diagnosis":{"type":["string","null"]},"counterProposal":{"default":null,"anyOf":[{"type":"object","properties":{"summary":{"type":"string"},"tradeoff":{"type":"string"},"actionKind":{"type":"string","enum":["adjust_request","raise_budget","use_template","manual_edit"]},"templateId":{"type":["string","null"]}},"required":["summary","tradeoff","actionKind","templateId"],"additionalProperties":false},{"type":"null"}]},"attempts":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","minimum":0,"maximum":9007199254740991},"failedGate":{"type":["string","null"]},"whatWasTried":{"type":["string","null"]},"semanticRemedyApplied":{"default":false,"type":"boolean"}},"required":["attempt","failedGate","whatWasTried","semanticRemedyApplied"],"additionalProperties":false}}},"required":["cause","blockingGate","diagnosis","counterProposal","attempts"],"additionalProperties":false},{"type":"null"}]},"createdAtTs":{"type":"number"},"finishedAtTs":{"type":["number","null"]},"attempts":{"default":[],"type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","minimum":0,"maximum":9007199254740991},"publishJobId":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"finishedAtTs":{"type":["number","null"]},"failedGates":{"type":"array","items":{"type":"object","properties":{"gateKey":{"type":"string","enum":["static_contract","deps_locked","org_secrets_resolved","required_tests_passed","bundle_size","runtime_timeout","chain_cost","scan_cost","graph_consistency","ai_tests_generated","ai_tests_passed","user_tests_passed","lambda_deploy"],"description":"Which gate this result belongs to."},"status":{"type":"string","enum":["pending","running","passed","failed","warning","blocked"],"description":"'pending' | 'running' | 'passed' | 'failed' | 'warning' | 'blocked'. 'warning' passes with caveats; 'blocked' means an earlier gate's failure prevented this one from running."},"result":{"description":"Human-readable gate summary, when available.","type":["string","null"]},"detailsJson":{"description":"Structured gate details, when available.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"startedAtTs":{"description":"Gate start time, Unix epoch-ms, when started.","type":["number","null"]},"finishedAtTs":{"description":"Gate finish time, Unix epoch-ms, when finished.","type":["number","null"]}},"required":["gateKey","status"],"additionalProperties":false,"description":"One gate's result within a publish job. The gate-key vocabulary is owned by the publish-gate registry; the status vocabulary is identical to the custom-shipping-provider pipeline's so workers port cleanly."}}},"required":["attempt","publishJobId","status","finishedAtTs","failedGates"],"additionalProperties":false}},"pendingApproval":{"default":null,"anyOf":[{"type":"object","properties":{"changeSummary":{"type":["string","null"]},"construct":{"type":["string","null"]},"remedy":{"type":["string","null"]}},"required":["changeSummary","construct","remedy"],"additionalProperties":false},{"type":"null"}]}},"required":["id","status","purpose","attempt","maxAttempts","currentPublishJobId","baselineDraftS3Key","giveUp","createdAtTs","finishedAtTs","attempts","pendingApproval"],"additionalProperties":false},{"type":"null"}]}},"required":["rule","latestPublishJob","activeRepairRun"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Delete a rule

> \`\`\`http\
> DELETE /v25-10-beta/agentic-logic/rules/{ruleId}\
> \`\`\`\
> \
> Deletes a rule.\
> \
> \- Deletion is how a rule is retired, and is legal from every lifecycle state\
> &#x20; (\`draft\`, \`active\`, \`paused\`). There is no archive step and no archived state.\
> \- A rule referenced by a placement assignment or an experiment arm cannot be\
> &#x20; deleted; the error names each reference so you can unbind it.\
> \- Deletion is permanent: the rule's compute is released and its stored\
> &#x20; artifacts are swept.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}":{"delete":{"operationId":"deleteAgenticLogicRule","summary":"Delete a rule","tags":["Agentic Logic"],"description":"```http\nDELETE /v25-10-beta/agentic-logic/rules/{ruleId}\n```\n\nDeletes a rule.\n\n- Deletion is how a rule is retired, and is legal from every lifecycle state\n  (`draft`, `active`, `paused`). There is no archive step and no archived state.\n- A rule referenced by a placement assignment or an experiment arm cannot be\n  deleted; the error names each reference so you can unbind it.\n- Deletion is permanent: the rule's compute is released and its stored\n  artifacts are swept.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Update a rule

> \`\`\`http\
> PATCH /v25-10-beta/agentic-logic/rules/{ruleId}\
> \`\`\`\
> \
> Updates a rule's name, description, settings, or builder-template\
> configuration. The response is \`{ rule }\`. This endpoint never changes the\
> rule's lifecycle state, and \`targetSurfaces\` cannot change.\
> \
> \- \`name\` (string, optional) — New merchant-facing name.\
> \- \`description\` (string, optional, 1–1024 characters) — New plain-language\
> &#x20; summary.\
> \- \`settings\` (object, optional) — New recommendation settings, the same shape\
> &#x20; as on create. Replaces the stored object whole: a partial object is not\
> &#x20; merged.\
> \- \`templateParams\` (object, optional) — New template parameters (builder rules\
> &#x20; only).\
> \- \`templateVersion\` (number, optional) — New template version (builder rules\
> &#x20; only; must be sent with \`templateParams\`).\
> \- \`authoringSessionId\` (string, optional) — The AI chat session that authored\
> &#x20; the rule.\
> \
> Settings and template changes take effect at the next publish; the currently\
> active version keeps serving until then.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}":{"patch":{"operationId":"updateAgenticLogicRule","summary":"Update a rule","tags":["Agentic Logic"],"description":"```http\nPATCH /v25-10-beta/agentic-logic/rules/{ruleId}\n```\n\nUpdates a rule's name, description, settings, or builder-template\nconfiguration. The response is `{ rule }`. This endpoint never changes the\nrule's lifecycle state, and `targetSurfaces` cannot change.\n\n- `name` (string, optional) — New merchant-facing name.\n- `description` (string, optional, 1–1024 characters) — New plain-language\n  summary.\n- `settings` (object, optional) — New recommendation settings, the same shape\n  as on create. Replaces the stored object whole: a partial object is not\n  merged.\n- `templateParams` (object, optional) — New template parameters (builder rules\n  only).\n- `templateVersion` (number, optional) — New template version (builder rules\n  only; must be sent with `templateParams`).\n- `authoringSessionId` (string, optional) — The AI chat session that authored\n  the rule.\n\nSettings and template changes take effect at the next publish; the currently\nactive version keeps serving until then.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New merchant-facing name.","type":"string","minLength":1},"description":{"description":"New plain-language rule summary.","type":"string","minLength":1,"maxLength":1024},"settings":{"description":"New recommendation settings. Replaces the stored object whole — a partial object is not merged. Takes effect at the next publish.","type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}}},"templateParams":{"description":"New template params for builder rules, validated against the template's params schema at write time.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"templateVersion":{"description":"Template artifact version the new params were authored against.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"authoringSessionId":{"description":"Id of the AI chat session that authored this rule, recorded by the workspace client once the session id is known (the create call is made by a tool that does not carry it). Re-sending the stored id is a no-op; a different id repoints the rule at that newer conversation, which is what a revision session does when it finishes.","type":"string","minLength":1}},"description":"Update a rule's mutable fields. Lifecycle state moves through the lifecycle verbs, never through this endpoint."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One recommendation rule: the org-scoped container that owns drafts, immutable versions, and placement assignments. The rule row carries lifecycle state; only 'active' rules are evaluable."}},"required":["rule"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Rule actions

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/actions/{action}\
> \`\`\`\
> \
> Performs a synchronous lifecycle action on a rule.\
> \
> \- \`pause\` — Stop serving the rule. Idempotent: pausing a paused rule returns its\
> &#x20; current state.\
> \- \`resume\` — Serve the rule again. Requires a published version; a\
> &#x20; never-published rule answers 409.\
> \- \`rollback\` — Instantly move the active-version pointer to an older published\
> &#x20; version. Requires \`version\` in the body; the rule must be \`active\`.\
> \
> Body: \`version\` (number, optional) — Publish number to activate. Required for\
> \`rollback\`, rejected for every other action.\
> \
> \- Publishing and gate dry runs are not actions here — they are asynchronous\
> &#x20; and have their own endpoints with a poll resource.\
> \- Retiring a rule is not an action here either — it is\
> &#x20; \`DELETE /v25-10-beta/agentic-logic/rules/{ruleId}\`. \`archive\` and \`restore\` are\
> &#x20; rejected.\
> \- The response returns the rule; \`rollback\` additionally returns\
> &#x20; \`activeVersionId\`.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/actions/{action}":{"post":{"operationId":"agenticLogicRuleAction","summary":"Rule actions","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/actions/{action}\n```\n\nPerforms a synchronous lifecycle action on a rule.\n\n- `pause` — Stop serving the rule. Idempotent: pausing a paused rule returns its\n  current state.\n- `resume` — Serve the rule again. Requires a published version; a\n  never-published rule answers 409.\n- `rollback` — Instantly move the active-version pointer to an older published\n  version. Requires `version` in the body; the rule must be `active`.\n\nBody: `version` (number, optional) — Publish number to activate. Required for\n`rollback`, rejected for every other action.\n\n- Publishing and gate dry runs are not actions here — they are asynchronous\n  and have their own endpoints with a poll resource.\n- Retiring a rule is not an action here either — it is\n  `DELETE /v25-10-beta/agentic-logic/rules/{ruleId}`. `archive` and `restore` are\n  rejected.\n- The response returns the rule; `rollback` additionally returns\n  `activeVersionId`.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true},{"in":"path","name":"action","schema":{"type":"string","enum":["pause","resume","rollback"]},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"description":"Publish number of the version to activate. Required for `rollback`, rejected for the other actions.","type":"integer","minimum":1,"maximum":9007199254740991}},"description":"Lifecycle action body for the external actions route. `rollback` requires `version`; every other action rejects it."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"One recommendation rule: the org-scoped container that owns drafts, immutable versions, and placement assignments. The rule row carries lifecycle state; only 'active' rules are evaluable."},"activeVersionId":{"description":"Id of the version row now serving as active. Present after `rollback` only.","type":"string"}},"required":["rule"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Cancel a check run

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/cancel-checks\
> \`\`\`\
> \
> Stops the check run a job belongs to. It works on jobs of either \`mode\`: a\
> \`dry\_run\`, including one started by run-gates, or a \`publish\`.\
> \
> \- \`publishJobId\` (uuid, required) — The job to cancel. It must belong to the\
> &#x20; rule; an unknown job answers 404.\
> \
> The cancel is live when the named job is still \`queued\` or \`running\`, or when\
> the rule's AI repair run is working that job. A live cancel stops all of these\
> in one transaction:\
> \
> \- the named job, if it is still in flight;\
> \- the rule's live repair run, which ends \`abandoned\` and starts no further\
> &#x20; attempts;\
> \- every other \`queued\` or \`running\` job of the rule, publish or dry run.\
> \
> Cancelled jobs end \`cancelled\`. Gates that were mid-run go back to \`pending\`;\
> finished gates keep their results. A \`publish\` job cancelled before it promotes\
> creates no version and leaves the active version unchanged.\
> \
> The response is \`{ job, cancelled }\`. \`job\` is the named job after the request,\
> in the \[poll]\(#poll-a-publish-job) shape. \`cancelled\` is \`true\` when this\
> request stopped anything. A \`failed\` job whose repair run this request stopped\
> stays \`failed\`, with \`cancelled: true\`.\
> \
> \`cancelled\` is \`false\` when the named job had already finished (\`succeeded\`,\
> \`failed\`, or \`cancelled\`) and no repair run is working it. Nothing changes\
> then, and other jobs of the rule keep running. Repeating a cancel is safe. A\
> \`succeeded\` publish is not undone; use \`rollback\` for that.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/cancel-checks":{"post":{"operationId":"cancelAgenticLogicRuleChecks","summary":"Cancel a check run","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/cancel-checks\n```\n\nStops the check run a job belongs to. It works on jobs of either `mode`: a\n`dry_run`, including one started by run-gates, or a `publish`.\n\n- `publishJobId` (uuid, required) — The job to cancel. It must belong to the\n  rule; an unknown job answers 404.\n\nThe cancel is live when the named job is still `queued` or `running`, or when\nthe rule's AI repair run is working that job. A live cancel stops all of these\nin one transaction:\n\n- the named job, if it is still in flight;\n- the rule's live repair run, which ends `abandoned` and starts no further\n  attempts;\n- every other `queued` or `running` job of the rule, publish or dry run.\n\nCancelled jobs end `cancelled`. Gates that were mid-run go back to `pending`;\nfinished gates keep their results. A `publish` job cancelled before it promotes\ncreates no version and leaves the active version unchanged.\n\nThe response is `{ job, cancelled }`. `job` is the named job after the request,\nin the [poll](#poll-a-publish-job) shape. `cancelled` is `true` when this\nrequest stopped anything. A `failed` job whose repair run this request stopped\nstays `failed`, with `cancelled: true`.\n\n`cancelled` is `false` when the named job had already finished (`succeeded`,\n`failed`, or `cancelled`) and no repair run is working it. Nothing changes\nthen, and other jobs of the rule keep running. Repeating a cancel is safe. A\n`succeeded` publish is not undone; use `rollback` for that.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"publishJobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["publishJobId"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string","description":"Publish-job id (uuid) — the handle returned by the publish endpoint."},"ruleId":{"type":"string","description":"Rule the job publishes (uuid)."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"'queued' | 'running' | 'succeeded' | 'failed'."},"mode":{"type":"string","enum":["publish","dry_run"],"description":"'publish' (runs every gate and promotes a version on success) | 'dry_run' (validation gates only, never promotes). What the job IS — a reader cannot infer it from status while the job is still in flight."},"startedAtTs":{"description":"Worker start time, Unix epoch-ms; null while queued.","type":["number","null"]},"finishedAtTs":{"description":"Terminal time, Unix epoch-ms; null until the job finishes.","type":["number","null"]},"resultingVersionId":{"description":"Version the job promoted, when it succeeded in publish mode; null otherwise (and null again if that version is later deleted by retention).","type":["string","null"]},"gates":{"type":"array","items":{"type":"object","properties":{"gateKey":{"type":"string","enum":["static_contract","deps_locked","org_secrets_resolved","required_tests_passed","bundle_size","runtime_timeout","chain_cost","scan_cost","graph_consistency","ai_tests_generated","ai_tests_passed","user_tests_passed","lambda_deploy"],"description":"Which gate this result belongs to."},"status":{"type":"string","enum":["pending","running","passed","failed","warning","blocked"],"description":"'pending' | 'running' | 'passed' | 'failed' | 'warning' | 'blocked'. 'warning' passes with caveats; 'blocked' means an earlier gate's failure prevented this one from running."},"result":{"description":"Human-readable gate summary, when available.","type":["string","null"]},"detailsJson":{"description":"Structured gate details, when available.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"startedAtTs":{"description":"Gate start time, Unix epoch-ms, when started.","type":["number","null"]},"finishedAtTs":{"description":"Gate finish time, Unix epoch-ms, when finished.","type":["number","null"]}},"required":["gateKey","status"],"additionalProperties":false,"description":"One gate's result within a publish job. The gate-key vocabulary is owned by the publish-gate registry; the status vocabulary is identical to the custom-shipping-provider pipeline's so workers port cleanly."},"description":"Per-gate results, in pipeline order."}},"required":["id","ruleId","status","mode","startedAtTs","finishedAtTs","resultingVersionId","gates"],"additionalProperties":false,"description":"One publish job: the async unit that runs the gate pipeline against a frozen draft snapshot and, in publish mode, promotes a new active version on success."},"cancelled":{"type":"boolean"}},"required":["job","cancelled"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Get a code rule's draft

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}/draft\
> \`\`\`\
> \
> Gets the saved draft (source, user tests, dependencies) of a code rule. Secret\
> values never appear in a draft: rule source references organization secrets by\
> sentinel name only.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/draft":{"get":{"operationId":"getAgenticLogicRuleDraft","summary":"Get a code rule's draft","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}/draft\n```\n\nGets the saved draft (source, user tests, dependencies) of a code rule. Secret\nvalues never appear in a draft: rule source references organization secrets by\nsentinel name only.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"anyOf":[{"type":"object","properties":{"ruleId":{"type":"string","description":"Owning rule id (uuid)."},"source":{"description":"Draft rule source code, or null when nothing has been saved yet.","type":["string","null"]},"userTestSuite":{"description":"User-authored test suite saved with the draft, or null when none exists.","type":["string","null"]},"generatedTestSuite":{"description":"The AI-generated test suite carried with the draft, or null when none has been generated yet. Reused across publishes and dry runs: the publish pipeline regenerates it only when the rule's inputs or contract surface have moved, and writes the result back here.","type":["string","null"]},"dependencies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"npm package name."},"version":{"type":"string","minLength":1,"description":"Requested semver range."}},"required":["name","version"],"additionalProperties":false,"description":"One npm dependency recorded on a rule draft. Read-only history: Agentic Logic admits no third-party package, so a request that declares one is refused."},"description":"Always empty for a draft saved under the current contract. Agentic Logic rules run with no third-party npm packages — rules read commerce state through the injected SDK — so the field only ever carries what an older draft stored."},"updatedByUserId":{"description":"User who last saved the draft, or null.","type":["string","null"]},"updatedByUser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},{"type":"null"}],"description":"Display summary for the user who last saved the draft, or null when the user is not known."},"lastUpdateTs":{"type":"number","description":"Last save time, Unix epoch-ms."},"origin":{"anyOf":[{"type":"string","enum":["chat","manual"]},{"type":"null"}],"description":"How the draft source came to be: 'chat' when applied from the workspace AI chat and untouched since, 'manual' when a person authored or last edited it, null for drafts saved before provenance was recorded."},"graph":{"anyOf":[{"type":"object","properties":{"version":{"type":"number","const":1,"description":"Graph wire-format version. Currently 1."},"nodes":{"minItems":2,"maxItems":150,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable node id, unique within the graph. For kind 'branch', MUST equal the attempt() base label (a static string literal in the code). Runtime attempt instances are drill-in data on the node, never nodes of their own."},"kind":{"type":"string","enum":["input","branch","generator","filter","sort","limit","exclusions","output","fallback-terminal"],"description":"'input' | 'branch' | 'generator' | 'filter' | 'sort' | 'limit' | 'exclusions' | 'output' | 'fallback-terminal'. Branch nodes mirror attempt() bases; pipeline kinds describe the flow inside or after a branch, while Exclusions is the platform-owned final filter."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"Short card title shown on the node."},"summary":{"description":"One plain-language sentence describing what the node does.","type":"string","maxLength":500},"branchId":{"description":"Owning branch node id, set ONLY on generator/filter/sort/limit nodes that run inside that branch; absent for shared pipeline nodes and always absent on 'input', 'branch', 'exclusions', 'output' and 'fallback-terminal' nodes — a branch never names itself.","type":"string","minLength":1,"maxLength":200},"meta":{"description":"Kind-specific structured details (e.g. generator source, aggregate itemCount + sampleItems, limit N). Aggregates belong here — never one node per item.","type":"object","properties":{"itemCount":{"description":"Aggregate count of items the node covers (e.g. a generator drawing from a 1000-product list).","type":"integer","minimum":0,"maximum":9007199254740991},"sampleItems":{"description":"Up to five representative item names for drill-in display; never the full list.","maxItems":5,"type":"array","items":{"type":"string"}},"condition":{"description":"Plain-language matching clause for branch/filter nodes, phrased for a merchant ('in stock right now', 'cart contains a tagged cover-up'). The MATCHING card body.","type":"string","maxLength":300},"conditionSubject":{"description":"Which request context a branch node's condition chip is about — 'cart' (the default when absent), 'delivery' (request.shipping.delivery: selected option, local pickup, cost, carrier, transit days), 'shipping' (gap, threshold, tiers, state), 'customer' (ordersCount, tags), 'page' (request.pageProduct), 'order' (request.order), 'time' (request.evaluatedAt). Drives the row-header sentence; absent on always-matching branches and on every non-branch node.","type":"string","enum":["cart","delivery","shipping","customer","page","order","time"]},"sortKey":{"description":"Plain-language sort criterion for sort nodes ('Best sellers'). The SORTED BY card body.","type":"string","maxLength":120},"limit":{"description":"Maximum number of items a limit node lets through. Rendered as 'UP TO n products'.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":{}}},"required":["id","kind","label"],"additionalProperties":false,"description":"One node in a rule graph. For kind 'branch' the id IS the attempt() base label lexed from the rule's code — that identity is what the graph_consistency gate and the branchFired telemetry join on."},"description":"Graph nodes, at most RULE_GRAPH_MAX_NODES. Large inputs must be aggregated into node meta, never expanded per item."},"edges":{"maxItems":400,"type":"array","items":{"type":"object","properties":{"from":{"type":"string","minLength":1,"description":"Source node id."},"to":{"type":"string","minLength":1,"description":"Target node id."},"kind":{"type":"string","enum":["flow","fallback"],"description":"'flow' = data/control flow; 'fallback' = taken when the source produced nothing (branch miss or empty output). Fallback edges may only terminate at a branch or the fallback-terminal."}},"required":["from","to","kind"],"additionalProperties":false,"description":"One directed edge in a rule graph."},"description":"Directed edges between node ids, at most RULE_GRAPH_MAX_EDGES."}},"required":["version","nodes","edges"],"additionalProperties":false,"description":"The rule's graph artifact: a renderer-agnostic node/edge description of the rule's selection logic, versioned alongside the code. Carries NO geometry — layout is computed client-side. Produced deterministically for template rules and emitted by the authoring agent for custom-code rules, then verified by the graph_consistency gate."},{"type":"null"}],"description":"The rule-graph artifact saved alongside the draft source, or null when none has been emitted yet (pre-graph drafts, human-authored code). Persisted only after save-time validation against the submitted code."},"contentFingerprint":{"description":"SHA-256 identity of the code workspace (source, user tests, generated tests). Equal draft and active-version fingerprints mean the draft has nothing to apply. Null for template rules, and for rows not yet fingerprinted.","type":["string","null"]}},"required":["ruleId","source","userTestSuite","generatedTestSuite","dependencies","updatedByUserId","updatedByUser","lastUpdateTs","origin","graph","contentFingerprint"],"additionalProperties":false,"description":"The rule's single mutable draft (exactly one per rule, overwritten on save). Source and user tests live in S3; dependencies live on the row."},{"type":"null"}]}},"required":["draft"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Save a code rule's draft

> \`\`\`http\
> PUT /v25-10-beta/agentic-logic/rules/{ruleId}/draft\
> \`\`\`\
> \
> Saves the draft of a code rule. The response is \`{ draft }\`. A builder rule\
> answers 400.\
> \
> \- \`source\` (string, required) — The rule source.\
> \- \`dependencies\` (array, optional) — Must be empty: rules run with no npm\
> &#x20; packages.\
> \- \`userTestSuite\` / \`generatedTestSuite\` (string, optional) — Omit to keep the\
> &#x20; stored suite; send \`""\` to clear it.\
> \- \`validationScenarios\` (array, optional) — Scenarios the publish checks run\
> &#x20; the rule against. Omit to keep the stored ones; send \`\[]\` to discard them.\
> \- \`graph\` (object, optional) — The rule graph for this source, checked against\
> &#x20; it at save time. When omitted, the stored graph is kept only if the source\
> &#x20; is unchanged.\
> \- \`origin\` (\`chat\` or \`manual\`, optional) — Where the source came from. Omit to\
> &#x20; keep the stored value.\
> \- \`autoAssist\` (boolean, optional) — Whether the save starts AI assistance.\
> &#x20; Defaults to \`true\`. Send \`false\` to only store the draft (see below). Applies\
> &#x20; to this call only; it is not stored on the rule.\
> \
> Every save replaces the previous draft. Publish snapshots the draft, so an\
> in-flight publish is not affected by a later save. Unless \`autoAssist\` is\
> \`false\`, a save also:\
> \
> \- Regenerates the rule graph with AI when the saved draft has no graph.\
> \- Regenerates the AI-generated validation scenarios when they no longer cover\
> &#x20; the source's \`attempt()\` branches. Scenarios you authored are kept.\
> \
> The first save of a \`draft\` rule that has never had a publish job, and that\
> does not send \`autoAssist: false\`, also starts a dry run of the publish checks. If the checks fail, an AI repair loop rewrites\
> the draft and runs them again, within its attempt, time, and cost limits. Once\
> the checks pass, the rule is published without any further call. If a rewrite\
> changed what the rule does, the loop stops instead and leaves the rewritten\
> draft for a person to publish.\
> \
> Saving a draft does not stop a running repair loop. If you save while the loop\
> is rewriting, the loop's rewrite is dropped, that attempt counts against its\
> limit, and the loop decides its next step from your draft.\
> \
> With \`autoAssist: false\`, the save starts neither the regeneration above nor\
> the dry run, and it does not stop a repair loop that is already running. A\
> later save without the flag still starts the dry run while the rule has never\
> had a publish job. A later publish still works: with no graph the graph\
> check passes with a note, with no scenarios the default scenario is used, and\
> the AI test suite is generated at publish time.\
> \
> A save that omits \`validationScenarios\` keeps the stored ones unchanged, so\
> scenarios from an earlier save, including AI-generated ones, carry forward and\
> may no longer match the new source's branches. While they do not, the\
> \[scenarios listing]\(#list-a-rules-scenarios) reports \`pending\` until a save\
> without \`autoAssist: false\` regenerates them, or a save sends a full generated\
> set: sent scenarios replace the stored ones rather than adding to them.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/draft":{"put":{"operationId":"saveAgenticLogicRuleDraft","summary":"Save a code rule's draft","tags":["Agentic Logic"],"description":"```http\nPUT /v25-10-beta/agentic-logic/rules/{ruleId}/draft\n```\n\nSaves the draft of a code rule. The response is `{ draft }`. A builder rule\nanswers 400.\n\n- `source` (string, required) — The rule source.\n- `dependencies` (array, optional) — Must be empty: rules run with no npm\n  packages.\n- `userTestSuite` / `generatedTestSuite` (string, optional) — Omit to keep the\n  stored suite; send `\"\"` to clear it.\n- `validationScenarios` (array, optional) — Scenarios the publish checks run\n  the rule against. Omit to keep the stored ones; send `[]` to discard them.\n- `graph` (object, optional) — The rule graph for this source, checked against\n  it at save time. When omitted, the stored graph is kept only if the source\n  is unchanged.\n- `origin` (`chat` or `manual`, optional) — Where the source came from. Omit to\n  keep the stored value.\n- `autoAssist` (boolean, optional) — Whether the save starts AI assistance.\n  Defaults to `true`. Send `false` to only store the draft (see below). Applies\n  to this call only; it is not stored on the rule.\n\nEvery save replaces the previous draft. Publish snapshots the draft, so an\nin-flight publish is not affected by a later save. Unless `autoAssist` is\n`false`, a save also:\n\n- Regenerates the rule graph with AI when the saved draft has no graph.\n- Regenerates the AI-generated validation scenarios when they no longer cover\n  the source's `attempt()` branches. Scenarios you authored are kept.\n\nThe first save of a `draft` rule that has never had a publish job, and that\ndoes not send `autoAssist: false`, also starts a dry run of the publish checks. If the checks fail, an AI repair loop rewrites\nthe draft and runs them again, within its attempt, time, and cost limits. Once\nthe checks pass, the rule is published without any further call. If a rewrite\nchanged what the rule does, the loop stops instead and leaves the rewritten\ndraft for a person to publish.\n\nSaving a draft does not stop a running repair loop. If you save while the loop\nis rewriting, the loop's rewrite is dropped, that attempt counts against its\nlimit, and the loop decides its next step from your draft.\n\nWith `autoAssist: false`, the save starts neither the regeneration above nor\nthe dry run, and it does not stop a repair loop that is already running. A\nlater save without the flag still starts the dry run while the rule has never\nhad a publish job. A later publish still works: with no graph the graph\ncheck passes with a note, with no scenarios the default scenario is used, and\nthe AI test suite is generated at publish time.\n\nA save that omits `validationScenarios` keeps the stored ones unchanged, so\nscenarios from an earlier save, including AI-generated ones, carry forward and\nmay no longer match the new source's branches. While they do not, the\n[scenarios listing](#list-a-rules-scenarios) reports `pending` until a save\nwithout `autoAssist: false` regenerates them, or a save sends a full generated\nset: sent scenarios replace the stored ones rather than adding to them.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Draft rule source code."},"userTestSuite":{"description":"User-authored test suite to persist with the draft. Omit to leave the existing suite untouched; send an empty string to clear it.","type":"string"},"generatedTestSuite":{"description":"Edits to the AI-generated test suite. Omit to leave the stored suite untouched; send an empty string to clear it and let the next publish generate a fresh one. An explicit suite is stored as hand-authored, so the next publish runs it to decide whether it still covers the rule rather than assuming either way.","type":"string"},"dependencies":{"default":[],"description":"Must be empty. Agentic Logic rules run with no third-party npm packages: the rule runtime's no-network, no-clock boundary is scoped to the rule's own files, and a bundled package would run inside the rule with that boundary drawn around nothing. Read commerce state through the injected SDK instead.","maxItems":0,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"npm package name."},"version":{"type":"string","minLength":1,"description":"Requested semver range."}},"required":["name","version"],"description":"One npm dependency recorded on a rule draft. Read-only history: Agentic Logic admits no third-party package, so a request that declares one is refused."}},"validationScenarios":{"description":"Request-side scenarios the publish gates evaluate the rule against. Omit to leave the draft's existing scenarios untouched; send an empty array to discard them. Publishing requires at least one. There is no read-side half to save: gate-time SDK reads are served live, and the scan-cost report is derived from the validation run itself rather than persisted here.","type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable scenario name, shown in test results and gate details."},"request":{"type":"object","properties":{"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the recommendation will render on. There is deliberately no 'headless' value — API callers declare the surface they render."},"cart":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"ISO-4217 currency code the shopper pays in. Every money field in this cart is in it except `shopSubtotal`."},"subtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart merchandise subtotal in integer minor units of `currency`, before shipping and taxes. Do not compare it against a money threshold: thresholds are in the store's currency, so use `shopSubtotal ?? subtotal`."},"shopSubtotal":{"description":"The same subtotal converted to the store's default currency, in integer minor units of that currency. Money thresholds compare against this, so a $50 threshold means $50 whatever the shopper pays in. Equal to `subtotal` when the cart is already in the store's currency. null when the store's currency or the cart currency's exchange rate is not known yet, so no threshold can match. Absent when serving did not compute it (scenario and test carts), so read `shopSubtotal ?? subtotal`.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total unit quantity across all lines (sum of line quantities) — units, not the count of distinct lines."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line in the visitor's current cart."},"description":"The cart lines."}},"required":["currency","subtotal","itemCount","lines"],"description":"Snapshot of the visitor's current cart. An empty cart (zero lines) is a legal cart — distinct from cart: null, which means the surface has no cart at all (post-purchase)."},{"type":"null"}],"description":"Current cart, or null when the surface has no cart (post-purchase). An empty cart is legal onsite — branch on surface, not on cart == null."},"order":{"anyOf":[{"type":"object","properties":{"orderId":{"type":"string","description":"Shopify order GID (gid://shopify/Order/<n>)."},"checkoutToken":{"description":"Shopify checkout token for the checkout that produced this order, when available.","type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Order creation time as an ISO-8601 UTC timestamp."},"currencyCode":{"type":"string","description":"ISO-4217 shop currency code the order's money fields are denominated in."},"presentmentCurrency":{"type":"string","description":"ISO-4217 currency code the shopper saw at checkout, which may differ from `currencyCode`."},"itemsSubtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Merchandise subtotal after line-level discounts but before order-level discounts, shipping, and taxes. Integer minor units."},"discountTotal":{"description":"Total order-level discount amount in integer minor units, when any.","type":"integer","minimum":0,"maximum":9007199254740991},"shippingTotal":{"description":"Shipping charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"taxTotal":{"description":"Taxes charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"What the shopper was actually charged, in integer minor units."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}},"title":{"description":"Product title at purchase time, when available.","type":"string"},"vendor":{"description":"Product vendor at purchase time, when available.","type":"string"},"productType":{"description":"Shopify product type at purchase time, when available.","type":"string"},"sellingPlanId":{"description":"Shopify selling-plan GID (gid://shopify/SellingPlan/<n>) when the line was purchased on a subscription.","type":"string"},"discountAllocations":{"description":"Line-level discount allocations applied to this line, when any.","type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Discount amount allocated to the line, in integer minor units of the order's currency."},"title":{"description":"Discount title or code as shown on the order, when available.","type":"string"}},"required":["amount"],"description":"One discount amount allocated to an order line."}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line on the completed order. Extends the cart-line shape with catalog metadata that is available once the order exists."},"description":"The purchased order lines."}},"required":["orderId","createdAt","currencyCode","presentmentCurrency","itemsSubtotal","total","lines"],"description":"The completed order a post-purchase surface is rendered against. First-class on the post-purchase surface only; null everywhere else. Deliberately carries NO customer field — the top-level request `customer` is the single customer reference."},{"type":"null"}],"description":"Completed order — first-class on the post-purchase surface only; null elsewhere."},"pageProduct":{"anyOf":[{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID of the product being viewed (gid://shopify/Product/<n>). The bare numeric id the Shopify admin shows is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"handle":{"type":"string","description":"Shopify product handle (URL slug) of the product being viewed."},"targeting":{"description":"Theme product facts used for onsite product targeting. Null when the theme has no product data; product-targeted branches then do not match. Absent from clients that predate the field; serving then reads the facts from Shopify when the rule targets the product.","anyOf":[{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}},"inventory":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lowestVariantPrice":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tags","collectionIds","inventory","lowestVariantPrice"]},{"type":"null"}]}},"required":["productId","handle"],"description":"The product a PDP placement is rendered on. Populated for onsite product-page placements only; null everywhere else."},{"type":"null"}],"description":"Product the placement's page is about — onsite PDP placements only; null everywhere else."},"customer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Shopify customer GID (gid://shopify/Customer/<n>)."},"ordersCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Number of orders this customer has placed, or null when the surface did not supply it — checkout supplies it for a verified buyer when the app's protected-customer-data grant covers it; onsite and post-purchase never do. Integer, >= 0, when present. Null-check it, or use sdk.getCustomer() for a count that does not depend on the grant."},"amountSpent":{"description":"Lifetime spend aggregate, when known.","type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Lifetime amount spent in integer minor units of `currency`."},"currency":{"type":"string","description":"ISO-4217 currency code `amount` is denominated in."}},"required":["amount","currency"]}},"required":["id","ordersCount"],"description":"Minimal identified-customer context, or null for guests. PII-MINIMAL GUARANTEE: this object carries ids, counts, and money aggregates ONLY — no email, name, phone, or address field may ever be added here. That is a contract property, not a data-availability accident; richer profile data is fetched at rule runtime via sdk.getCustomer()."},{"type":"null"}],"description":"Identified customer, or null for guests."},"shipping":{"type":"object","properties":{"state":{"type":"string","enum":["resolved","assumed","not-applicable","unavailable"],"description":"'resolved' = thresholds are known facts for this visitor; 'assumed' = best-effort defaults that may be wrong, so treat them as a hint rather than a fact when steering; 'not-applicable' = the store has no shipping incentive here, and the order may not be shipping at all; 'unavailable' = the shipping facts could not be read before the serving deadline (a Shopify read failed or timed out), so no threshold field is present and nothing is known — never read it as 'no incentive'."},"currency":{"type":"string","description":"ISO-4217 currency code the threshold fields are denominated in. Always present, even when state is 'not-applicable'."},"freeShippingThreshold":{"description":"Cart subtotal at which shipping becomes free, in integer minor units — pre-resolved to the visitor's assigned variation's threshold. Absent when there is no free-shipping incentive.","type":"integer","minimum":0,"maximum":9007199254740991},"remainingToFreeShipping":{"description":"How much more the visitor must add to qualify for free shipping, in integer minor units. 0 = already qualifies; absent or null = unresolvable.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"tiers":{"description":"Tiered incentive ladder in ascending threshold order, when the store runs tiered incentives.","type":"array","items":{"type":"object","properties":{"threshold":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart subtotal at which this tier unlocks, in integer minor units of the shipping context's currency."},"label":{"type":"string","description":"Shopper-facing label for the tier (e.g. 'Free shipping')."}},"required":["threshold","label"],"description":"One rung of a tiered shipping-incentive ladder."}},"delivery":{"description":"The delivery options Shopify computed for this checkout, as observed facts rather than merchant settings. Present only at checkout, and only once Shopify has computed options (an address or a pickup selection exists); absent onsite, post-purchase, and on first render. Present under every state, including 'not-applicable' for local pickup.","type":"object","properties":{"isLocalPickup":{"type":"boolean","description":"True when every selected delivery option is a pickup option — the buyer is not shipping anything."},"selected":{"description":"The buyer's currently selected option, when exactly one delivery group has a selection. Absent before the buyer picks, and when multiple groups (a subscription plus a one-time purchase) select different options — read `options` then.","type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"]},"options":{"type":"array","items":{"type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"],"description":"One delivery option Shopify offered the buyer at checkout — a shipping rate or a pickup choice — in the rule envelope's minor-unit money convention. PII-MINIMAL: option facts only, never the destination."},"description":"Every option Shopify computed, flattened across delivery groups, in Shopify's order. A zero-cost non-pickup option means the buyer already qualifies for free shipping."}},"required":["isLocalPickup","options"]}},"required":["state","currency"],"description":"Shipping-incentive context. Required — 'not-applicable' is expressed in-band via its state field, never by omitting the object."},"country":{"description":"OPTIONAL. ISO-3166-1 alpha-2 code of the market this request should be evaluated in, e.g. 'CA'. Omit it (or send null) and the platform evaluates in its default market, 'US'. Name it whenever the cart is denominated in a non-shop currency, so the catalog reads run in the same market the money does.","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"cartFingerprint":{"description":"Opaque client-supplied fingerprint of the cart state this request was built from. The engine echoes it verbatim on the result envelope so the rendering surface can compare and discard late results.","type":"string"},"placementId":{"description":"Optional at authoring time; omit it and the server fills the rule's own id when the draft is saved. Wire shape only — publish gates evaluate the rule directly, never a placement assignment, so no real placement is needed and the author should never be asked for one.","type":"string"}},"required":["surface","cart","order","pageProduct","customer","shipping"],"description":"The recommendation request the scenario evaluates. `placementId` and `surface` here are wire shape, not references: gates evaluate the rule directly, never an assignment, so no real placement is involved."},"context":{"description":"Optional evaluation context override. When absent the harness supplies a representative preview context.","type":"object","properties":{"isPreview":{"type":"boolean","description":"True when the evaluation is a preview (editor/test-lab) run rather than live traffic."},"slotsNeeded":{"type":"integer","minimum":0,"maximum":50,"description":"How many recommendation slots the placement wants filled. Non-negative integer, at most 50 — ZERO is reachable, because a placement can resolve to no slots, so a rule must answer zero with an empty envelope before it reads anything."},"excludeOutOfStock":{"default":true,"description":"The rule's out-of-stock setting. When true, every SDK catalog read and product recommendation drops products with no variant for sale, so rule code never filters stock itself. Defaults to true, the rule setting's own default. A read that passes its own `excludeOutOfStock` overrides it.","type":"boolean"}},"required":["isPreview","slotsNeeded"]},"evaluatedAt":{"description":"Optional author-pinned evaluation instant, epoch milliseconds UTC. When absent the harness stamps the publish job's own instant. Pin it to make a time-dependent scenario stable: a case like 'a 30-day supply ordered 34 days ago' needs both ends fixed, or its expected verdict drifts with the calendar.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":{"description":"Display copy for scenario pickers, phrased for a merchant (e.g. 'A cart that matches your matching cover-ups rule'). Absent on scenarios authored before display copy existed.","type":"string","maxLength":500},"targetBranchId":{"description":"The branch this scenario is designed to fire: the graph branch node id (=== the attempt() base label). Null marks the nothing-matches scenario whose cart clears no branch; absent means unannotated (typically hand-authored).","type":["string","null"]},"origin":{"description":"'authored' = written by a person or authoring agent alongside the rule; 'generated' = produced by the scenario-generation service. Regeneration replaces only 'generated' scenarios and never clobbers authored ones.","type":"string","enum":["authored","generated"]}},"required":["name","request"]}},"graph":{"description":"The rule-graph artifact emitted WITH this source. Validated at save time against the submitted code (branch node ids must equal the attempt() base labels; structure must be a capped DAG) and rejected with mismatch details on disagreement. Omit to clear any previously saved graph — a graph never outlives the source it described.","type":"object","properties":{"version":{"type":"number","const":1,"description":"Graph wire-format version. Currently 1."},"nodes":{"minItems":2,"maxItems":150,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable node id, unique within the graph. For kind 'branch', MUST equal the attempt() base label (a static string literal in the code). Runtime attempt instances are drill-in data on the node, never nodes of their own."},"kind":{"type":"string","enum":["input","branch","generator","filter","sort","limit","exclusions","output","fallback-terminal"],"description":"'input' | 'branch' | 'generator' | 'filter' | 'sort' | 'limit' | 'exclusions' | 'output' | 'fallback-terminal'. Branch nodes mirror attempt() bases; pipeline kinds describe the flow inside or after a branch, while Exclusions is the platform-owned final filter."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"Short card title shown on the node."},"summary":{"description":"One plain-language sentence describing what the node does.","type":"string","maxLength":500},"branchId":{"description":"Owning branch node id, set ONLY on generator/filter/sort/limit nodes that run inside that branch; absent for shared pipeline nodes and always absent on 'input', 'branch', 'exclusions', 'output' and 'fallback-terminal' nodes — a branch never names itself.","type":"string","minLength":1,"maxLength":200},"meta":{"description":"Kind-specific structured details (e.g. generator source, aggregate itemCount + sampleItems, limit N). Aggregates belong here — never one node per item.","type":"object","properties":{"itemCount":{"description":"Aggregate count of items the node covers (e.g. a generator drawing from a 1000-product list).","type":"integer","minimum":0,"maximum":9007199254740991},"sampleItems":{"description":"Up to five representative item names for drill-in display; never the full list.","maxItems":5,"type":"array","items":{"type":"string"}},"condition":{"description":"Plain-language matching clause for branch/filter nodes, phrased for a merchant ('in stock right now', 'cart contains a tagged cover-up'). The MATCHING card body.","type":"string","maxLength":300},"conditionSubject":{"description":"Which request context a branch node's condition chip is about — 'cart' (the default when absent), 'delivery' (request.shipping.delivery: selected option, local pickup, cost, carrier, transit days), 'shipping' (gap, threshold, tiers, state), 'customer' (ordersCount, tags), 'page' (request.pageProduct), 'order' (request.order), 'time' (request.evaluatedAt). Drives the row-header sentence; absent on always-matching branches and on every non-branch node.","type":"string","enum":["cart","delivery","shipping","customer","page","order","time"]},"sortKey":{"description":"Plain-language sort criterion for sort nodes ('Best sellers'). The SORTED BY card body.","type":"string","maxLength":120},"limit":{"description":"Maximum number of items a limit node lets through. Rendered as 'UP TO n products'.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":{}}},"required":["id","kind","label"],"description":"One node in a rule graph. For kind 'branch' the id IS the attempt() base label lexed from the rule's code — that identity is what the graph_consistency gate and the branchFired telemetry join on."},"description":"Graph nodes, at most RULE_GRAPH_MAX_NODES. Large inputs must be aggregated into node meta, never expanded per item."},"edges":{"maxItems":400,"type":"array","items":{"type":"object","properties":{"from":{"type":"string","minLength":1,"description":"Source node id."},"to":{"type":"string","minLength":1,"description":"Target node id."},"kind":{"type":"string","enum":["flow","fallback"],"description":"'flow' = data/control flow; 'fallback' = taken when the source produced nothing (branch miss or empty output). Fallback edges may only terminate at a branch or the fallback-terminal."}},"required":["from","to","kind"],"description":"One directed edge in a rule graph."},"description":"Directed edges between node ids, at most RULE_GRAPH_MAX_EDGES."}},"required":["version","nodes","edges"]},"origin":{"description":"Provenance of the submitted source: 'chat' when the editor buffer was applied from the workspace AI chat and untouched since, 'manual' when a person authored or last edited it. Omit to leave the stored provenance untouched.","type":"string","enum":["chat","manual"]},"autoAssist":{"description":"Whether the save starts AI assistance. Defaults to true. False stores the draft without starting AI graph or scenario regeneration, the initial dry run, or a repair loop; a repair loop already running is not stopped. Applies to this call only.","type":"boolean"}},"required":["source"],"description":"Overwrite the rule's single draft. Publishing snapshots the draft at job creation, so later saves never change an in-flight publish."}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"object","properties":{"ruleId":{"type":"string","description":"Owning rule id (uuid)."},"source":{"description":"Draft rule source code, or null when nothing has been saved yet.","type":["string","null"]},"userTestSuite":{"description":"User-authored test suite saved with the draft, or null when none exists.","type":["string","null"]},"generatedTestSuite":{"description":"The AI-generated test suite carried with the draft, or null when none has been generated yet. Reused across publishes and dry runs: the publish pipeline regenerates it only when the rule's inputs or contract surface have moved, and writes the result back here.","type":["string","null"]},"dependencies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"npm package name."},"version":{"type":"string","minLength":1,"description":"Requested semver range."}},"required":["name","version"],"additionalProperties":false,"description":"One npm dependency recorded on a rule draft. Read-only history: Agentic Logic admits no third-party package, so a request that declares one is refused."},"description":"Always empty for a draft saved under the current contract. Agentic Logic rules run with no third-party npm packages — rules read commerce state through the injected SDK — so the field only ever carries what an older draft stored."},"updatedByUserId":{"description":"User who last saved the draft, or null.","type":["string","null"]},"updatedByUser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},{"type":"null"}],"description":"Display summary for the user who last saved the draft, or null when the user is not known."},"lastUpdateTs":{"type":"number","description":"Last save time, Unix epoch-ms."},"origin":{"anyOf":[{"type":"string","enum":["chat","manual"]},{"type":"null"}],"description":"How the draft source came to be: 'chat' when applied from the workspace AI chat and untouched since, 'manual' when a person authored or last edited it, null for drafts saved before provenance was recorded."},"graph":{"anyOf":[{"type":"object","properties":{"version":{"type":"number","const":1,"description":"Graph wire-format version. Currently 1."},"nodes":{"minItems":2,"maxItems":150,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable node id, unique within the graph. For kind 'branch', MUST equal the attempt() base label (a static string literal in the code). Runtime attempt instances are drill-in data on the node, never nodes of their own."},"kind":{"type":"string","enum":["input","branch","generator","filter","sort","limit","exclusions","output","fallback-terminal"],"description":"'input' | 'branch' | 'generator' | 'filter' | 'sort' | 'limit' | 'exclusions' | 'output' | 'fallback-terminal'. Branch nodes mirror attempt() bases; pipeline kinds describe the flow inside or after a branch, while Exclusions is the platform-owned final filter."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"Short card title shown on the node."},"summary":{"description":"One plain-language sentence describing what the node does.","type":"string","maxLength":500},"branchId":{"description":"Owning branch node id, set ONLY on generator/filter/sort/limit nodes that run inside that branch; absent for shared pipeline nodes and always absent on 'input', 'branch', 'exclusions', 'output' and 'fallback-terminal' nodes — a branch never names itself.","type":"string","minLength":1,"maxLength":200},"meta":{"description":"Kind-specific structured details (e.g. generator source, aggregate itemCount + sampleItems, limit N). Aggregates belong here — never one node per item.","type":"object","properties":{"itemCount":{"description":"Aggregate count of items the node covers (e.g. a generator drawing from a 1000-product list).","type":"integer","minimum":0,"maximum":9007199254740991},"sampleItems":{"description":"Up to five representative item names for drill-in display; never the full list.","maxItems":5,"type":"array","items":{"type":"string"}},"condition":{"description":"Plain-language matching clause for branch/filter nodes, phrased for a merchant ('in stock right now', 'cart contains a tagged cover-up'). The MATCHING card body.","type":"string","maxLength":300},"conditionSubject":{"description":"Which request context a branch node's condition chip is about — 'cart' (the default when absent), 'delivery' (request.shipping.delivery: selected option, local pickup, cost, carrier, transit days), 'shipping' (gap, threshold, tiers, state), 'customer' (ordersCount, tags), 'page' (request.pageProduct), 'order' (request.order), 'time' (request.evaluatedAt). Drives the row-header sentence; absent on always-matching branches and on every non-branch node.","type":"string","enum":["cart","delivery","shipping","customer","page","order","time"]},"sortKey":{"description":"Plain-language sort criterion for sort nodes ('Best sellers'). The SORTED BY card body.","type":"string","maxLength":120},"limit":{"description":"Maximum number of items a limit node lets through. Rendered as 'UP TO n products'.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":{}}},"required":["id","kind","label"],"additionalProperties":false,"description":"One node in a rule graph. For kind 'branch' the id IS the attempt() base label lexed from the rule's code — that identity is what the graph_consistency gate and the branchFired telemetry join on."},"description":"Graph nodes, at most RULE_GRAPH_MAX_NODES. Large inputs must be aggregated into node meta, never expanded per item."},"edges":{"maxItems":400,"type":"array","items":{"type":"object","properties":{"from":{"type":"string","minLength":1,"description":"Source node id."},"to":{"type":"string","minLength":1,"description":"Target node id."},"kind":{"type":"string","enum":["flow","fallback"],"description":"'flow' = data/control flow; 'fallback' = taken when the source produced nothing (branch miss or empty output). Fallback edges may only terminate at a branch or the fallback-terminal."}},"required":["from","to","kind"],"additionalProperties":false,"description":"One directed edge in a rule graph."},"description":"Directed edges between node ids, at most RULE_GRAPH_MAX_EDGES."}},"required":["version","nodes","edges"],"additionalProperties":false,"description":"The rule's graph artifact: a renderer-agnostic node/edge description of the rule's selection logic, versioned alongside the code. Carries NO geometry — layout is computed client-side. Produced deterministically for template rules and emitted by the authoring agent for custom-code rules, then verified by the graph_consistency gate."},{"type":"null"}],"description":"The rule-graph artifact saved alongside the draft source, or null when none has been emitted yet (pre-graph drafts, human-authored code). Persisted only after save-time validation against the submitted code."},"contentFingerprint":{"description":"SHA-256 identity of the code workspace (source, user tests, generated tests). Equal draft and active-version fingerprints mean the draft has nothing to apply. Null for template rules, and for rows not yet fingerprinted.","type":["string","null"]}},"required":["ruleId","source","userTestSuite","generatedTestSuite","dependencies","updatedByUserId","updatedByUser","lastUpdateTs","origin","graph","contentFingerprint"],"additionalProperties":false,"description":"The rule's single mutable draft (exactly one per rule, overwritten on save). Source and user tests live in S3; dependencies live on the row."}},"required":["draft"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Validate a code rule's draft

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/draft/validate\
> \`\`\`\
> \
> Runs the publish pipeline's \`static\_contract\` check (the \`evaluate\` export\
> contract, ESM compatibility, and the sandbox source guard) on the saved draft.\
> Nothing is published or persisted.\
> \
> \- No body. The response is \`{ "valid": true }\` or\
> &#x20; \`{ "valid": false, "message": "...", "details": { ... } | null }\`, where\
> &#x20; \`details\` carries the gate's structured fields (for example\
> &#x20; \`reason: "missing\_evaluate\_export"\`, or \`reason: "source\_guard\_refusal"\` with\
> &#x20; \`construct\` and \`remedy\`).\
> \- A failed check is a \`200\` with \`valid: false\`, not an error.\
> \- A builder rule answers 409: it has no code draft, so validate its template\
> &#x20; params instead. A code rule with no saved draft source answers 404.\
> \- Only the first publish gate runs; a valid draft can still fail a later gate\
> &#x20; (tests, budgets, deployment) when it is published.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/draft/validate":{"post":{"operationId":"validateAgenticLogicRuleDraft","summary":"Validate a code rule's draft","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/draft/validate\n```\n\nRuns the publish pipeline's `static_contract` check (the `evaluate` export\ncontract, ESM compatibility, and the sandbox source guard) on the saved draft.\nNothing is published or persisted.\n\n- No body. The response is `{ \"valid\": true }` or\n  `{ \"valid\": false, \"message\": \"...\", \"details\": { ... } | null }`, where\n  `details` carries the gate's structured fields (for example\n  `reason: \"missing_evaluate_export\"`, or `reason: \"source_guard_refusal\"` with\n  `construct` and `remedy`).\n- A failed check is a `200` with `valid: false`, not an error.\n- A builder rule answers 409: it has no code draft, so validate its template\n  params instead. A code rule with no saved draft source answers 404.\n- Only the first publish gate runs; a valid draft can still fail a later gate\n  (tests, budgets, deployment) when it is published.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"valid":{"type":"boolean","const":true}},"required":["valid"],"additionalProperties":false},{"type":"object","properties":{"valid":{"type":"boolean","const":false},"message":{"type":"string"},"details":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["valid","message","details"],"additionalProperties":false}],"type":"object"}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Evaluate a scenario

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/evaluate-scenario\
> \`\`\`\
> \
> Runs one scenario against the rule's saved draft (code rules) or current\
> template configuration (builder rules), under the rule's current settings.\
> nothing is persisted.\
> \
> \- \`scenario\` (object, required) — The full scenario. \`request.placementId\`\
> &#x20; defaults to the rule's own id.\
> \- A code rule with no saved draft source answers 404.\
> \
> The response is the admin's scenario preview (\`result\`, \`exclusions\`,\
> \`coverage\`, \`hydratedItems\`, \`onEmpty\`, \`evaluated\`), plus \`logs\` for code\
> rules:\
> \
> \- \`logs\` — What the rule's \`logger\` calls wrote during this run, in call\
> &#x20; order, as \`{ level, message, details?, invocationId?, timestamp }\`. Logs are\
> &#x20; returned when the rule completes, when it returns a malformed envelope\
> &#x20; (\`errorClass: "invalid\_envelope"\`), when it throws, and when it exceeds the\
> &#x20; budget. They are \`\[]\` when the rule logged nothing. A failed run whose output\
> &#x20; exceeds 256KB keeps only its earliest and latest entries, and the response\
> &#x20; then carries \`logsTruncated: true\`. A failure on the\
> &#x20; platform side, such as a failed SDK read, is rethrown by the sandbox runner\
> &#x20; without its output, so it returns an error result with no \`logs\` key. That\
> &#x20; includes a throw after the rule caught a failed SDK read; a budget overrun\
> &#x20; after one still returns its \`logs\`. Plain\
> &#x20; \`console.log\` output is not included. Builder rules have no \`logs\` key.\
> \- \`timestamp\` is ISO-8601 UTC host wall-clock time at the moment \`logger\` was\
> &#x20; called, with millisecond precision. Subtract two entries' timestamps to get\
> &#x20; the elapsed time between those calls, for example around a branch or a read.\
> \
> A code rule's preview runs under a fixed 10000ms budget\
> (\`AGENTIC\_LOGIC\_RUNTIME\_BUDGET\_MAX\_MS\`), whatever budget its placements\
> assign. The budget is wall-clock time for the whole \`evaluate\` call, SDK reads\
> included. A run that exceeds it returns an error result with\
> \`errorClass: "timeout"\` whose warning contains\
> \`Rule exceeded runtime ceiling of 10000ms\`. Its \`logs\` hold the entries written\
> before the timeout.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/evaluate-scenario":{"post":{"operationId":"evaluateAgenticLogicRuleScenario","summary":"Evaluate a scenario","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/evaluate-scenario\n```\n\nRuns one scenario against the rule's saved draft (code rules) or current\ntemplate configuration (builder rules), under the rule's current settings.\nnothing is persisted.\n\n- `scenario` (object, required) — The full scenario. `request.placementId`\n  defaults to the rule's own id.\n- A code rule with no saved draft source answers 404.\n\nThe response is the admin's scenario preview (`result`, `exclusions`,\n`coverage`, `hydratedItems`, `onEmpty`, `evaluated`), plus `logs` for code\nrules:\n\n- `logs` — What the rule's `logger` calls wrote during this run, in call\n  order, as `{ level, message, details?, invocationId?, timestamp }`. Logs are\n  returned when the rule completes, when it returns a malformed envelope\n  (`errorClass: \"invalid_envelope\"`), when it throws, and when it exceeds the\n  budget. They are `[]` when the rule logged nothing. A failed run whose output\n  exceeds 256KB keeps only its earliest and latest entries, and the response\n  then carries `logsTruncated: true`. A failure on the\n  platform side, such as a failed SDK read, is rethrown by the sandbox runner\n  without its output, so it returns an error result with no `logs` key. That\n  includes a throw after the rule caught a failed SDK read; a budget overrun\n  after one still returns its `logs`. Plain\n  `console.log` output is not included. Builder rules have no `logs` key.\n- `timestamp` is ISO-8601 UTC host wall-clock time at the moment `logger` was\n  called, with millisecond precision. Subtract two entries' timestamps to get\n  the elapsed time between those calls, for example around a branch or a read.\n\nA code rule's preview runs under a fixed 10000ms budget\n(`AGENTIC_LOGIC_RUNTIME_BUDGET_MAX_MS`), whatever budget its placements\nassign. The budget is wall-clock time for the whole `evaluate` call, SDK reads\nincluded. A run that exceeds it returns an error result with\n`errorClass: \"timeout\"` whose warning contains\n`Rule exceeded runtime ceiling of 10000ms`. Its `logs` hold the entries written\nbefore the timeout.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable scenario name, shown in test results and gate details."},"request":{"type":"object","properties":{"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the recommendation will render on. There is deliberately no 'headless' value — API callers declare the surface they render."},"cart":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"ISO-4217 currency code the shopper pays in. Every money field in this cart is in it except `shopSubtotal`."},"subtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart merchandise subtotal in integer minor units of `currency`, before shipping and taxes. Do not compare it against a money threshold: thresholds are in the store's currency, so use `shopSubtotal ?? subtotal`."},"shopSubtotal":{"description":"The same subtotal converted to the store's default currency, in integer minor units of that currency. Money thresholds compare against this, so a $50 threshold means $50 whatever the shopper pays in. Equal to `subtotal` when the cart is already in the store's currency. null when the store's currency or the cart currency's exchange rate is not known yet, so no threshold can match. Absent when serving did not compute it (scenario and test carts), so read `shopSubtotal ?? subtotal`.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total unit quantity across all lines (sum of line quantities) — units, not the count of distinct lines."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line in the visitor's current cart."},"description":"The cart lines."}},"required":["currency","subtotal","itemCount","lines"],"description":"Snapshot of the visitor's current cart. An empty cart (zero lines) is a legal cart — distinct from cart: null, which means the surface has no cart at all (post-purchase)."},{"type":"null"}],"description":"Current cart, or null when the surface has no cart (post-purchase). An empty cart is legal onsite — branch on surface, not on cart == null."},"order":{"anyOf":[{"type":"object","properties":{"orderId":{"type":"string","description":"Shopify order GID (gid://shopify/Order/<n>)."},"checkoutToken":{"description":"Shopify checkout token for the checkout that produced this order, when available.","type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Order creation time as an ISO-8601 UTC timestamp."},"currencyCode":{"type":"string","description":"ISO-4217 shop currency code the order's money fields are denominated in."},"presentmentCurrency":{"type":"string","description":"ISO-4217 currency code the shopper saw at checkout, which may differ from `currencyCode`."},"itemsSubtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Merchandise subtotal after line-level discounts but before order-level discounts, shipping, and taxes. Integer minor units."},"discountTotal":{"description":"Total order-level discount amount in integer minor units, when any.","type":"integer","minimum":0,"maximum":9007199254740991},"shippingTotal":{"description":"Shipping charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"taxTotal":{"description":"Taxes charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"What the shopper was actually charged, in integer minor units."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}},"title":{"description":"Product title at purchase time, when available.","type":"string"},"vendor":{"description":"Product vendor at purchase time, when available.","type":"string"},"productType":{"description":"Shopify product type at purchase time, when available.","type":"string"},"sellingPlanId":{"description":"Shopify selling-plan GID (gid://shopify/SellingPlan/<n>) when the line was purchased on a subscription.","type":"string"},"discountAllocations":{"description":"Line-level discount allocations applied to this line, when any.","type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Discount amount allocated to the line, in integer minor units of the order's currency."},"title":{"description":"Discount title or code as shown on the order, when available.","type":"string"}},"required":["amount"],"description":"One discount amount allocated to an order line."}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"description":"One line on the completed order. Extends the cart-line shape with catalog metadata that is available once the order exists."},"description":"The purchased order lines."}},"required":["orderId","createdAt","currencyCode","presentmentCurrency","itemsSubtotal","total","lines"],"description":"The completed order a post-purchase surface is rendered against. First-class on the post-purchase surface only; null everywhere else. Deliberately carries NO customer field — the top-level request `customer` is the single customer reference."},{"type":"null"}],"description":"Completed order — first-class on the post-purchase surface only; null elsewhere."},"pageProduct":{"anyOf":[{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID of the product being viewed (gid://shopify/Product/<n>). The bare numeric id the Shopify admin shows is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"handle":{"type":"string","description":"Shopify product handle (URL slug) of the product being viewed."},"targeting":{"description":"Theme product facts used for onsite product targeting. Null when the theme has no product data; product-targeted branches then do not match. Absent from clients that predate the field; serving then reads the facts from Shopify when the rule targets the product.","anyOf":[{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}},"inventory":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lowestVariantPrice":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tags","collectionIds","inventory","lowestVariantPrice"]},{"type":"null"}]}},"required":["productId","handle"],"description":"The product a PDP placement is rendered on. Populated for onsite product-page placements only; null everywhere else."},{"type":"null"}],"description":"Product the placement's page is about — onsite PDP placements only; null everywhere else."},"customer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Shopify customer GID (gid://shopify/Customer/<n>)."},"ordersCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Number of orders this customer has placed, or null when the surface did not supply it — checkout supplies it for a verified buyer when the app's protected-customer-data grant covers it; onsite and post-purchase never do. Integer, >= 0, when present. Null-check it, or use sdk.getCustomer() for a count that does not depend on the grant."},"amountSpent":{"description":"Lifetime spend aggregate, when known.","type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Lifetime amount spent in integer minor units of `currency`."},"currency":{"type":"string","description":"ISO-4217 currency code `amount` is denominated in."}},"required":["amount","currency"]}},"required":["id","ordersCount"],"description":"Minimal identified-customer context, or null for guests. PII-MINIMAL GUARANTEE: this object carries ids, counts, and money aggregates ONLY — no email, name, phone, or address field may ever be added here. That is a contract property, not a data-availability accident; richer profile data is fetched at rule runtime via sdk.getCustomer()."},{"type":"null"}],"description":"Identified customer, or null for guests."},"shipping":{"type":"object","properties":{"state":{"type":"string","enum":["resolved","assumed","not-applicable","unavailable"],"description":"'resolved' = thresholds are known facts for this visitor; 'assumed' = best-effort defaults that may be wrong, so treat them as a hint rather than a fact when steering; 'not-applicable' = the store has no shipping incentive here, and the order may not be shipping at all; 'unavailable' = the shipping facts could not be read before the serving deadline (a Shopify read failed or timed out), so no threshold field is present and nothing is known — never read it as 'no incentive'."},"currency":{"type":"string","description":"ISO-4217 currency code the threshold fields are denominated in. Always present, even when state is 'not-applicable'."},"freeShippingThreshold":{"description":"Cart subtotal at which shipping becomes free, in integer minor units — pre-resolved to the visitor's assigned variation's threshold. Absent when there is no free-shipping incentive.","type":"integer","minimum":0,"maximum":9007199254740991},"remainingToFreeShipping":{"description":"How much more the visitor must add to qualify for free shipping, in integer minor units. 0 = already qualifies; absent or null = unresolvable.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"tiers":{"description":"Tiered incentive ladder in ascending threshold order, when the store runs tiered incentives.","type":"array","items":{"type":"object","properties":{"threshold":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart subtotal at which this tier unlocks, in integer minor units of the shipping context's currency."},"label":{"type":"string","description":"Shopper-facing label for the tier (e.g. 'Free shipping')."}},"required":["threshold","label"],"description":"One rung of a tiered shipping-incentive ladder."}},"delivery":{"description":"The delivery options Shopify computed for this checkout, as observed facts rather than merchant settings. Present only at checkout, and only once Shopify has computed options (an address or a pickup selection exists); absent onsite, post-purchase, and on first render. Present under every state, including 'not-applicable' for local pickup.","type":"object","properties":{"isLocalPickup":{"type":"boolean","description":"True when every selected delivery option is a pickup option — the buyer is not shipping anything."},"selected":{"description":"The buyer's currently selected option, when exactly one delivery group has a selection. Absent before the buyer picks, and when multiple groups (a subscription plus a one-time purchase) select different options — read `options` then.","type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"]},"options":{"type":"array","items":{"type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}}}},"required":["isPickup","selected"],"description":"One delivery option Shopify offered the buyer at checkout — a shipping rate or a pickup choice — in the rule envelope's minor-unit money convention. PII-MINIMAL: option facts only, never the destination."},"description":"Every option Shopify computed, flattened across delivery groups, in Shopify's order. A zero-cost non-pickup option means the buyer already qualifies for free shipping."}},"required":["isLocalPickup","options"]}},"required":["state","currency"],"description":"Shipping-incentive context. Required — 'not-applicable' is expressed in-band via its state field, never by omitting the object."},"country":{"description":"OPTIONAL. ISO-3166-1 alpha-2 code of the market this request should be evaluated in, e.g. 'CA'. Omit it (or send null) and the platform evaluates in its default market, 'US'. Name it whenever the cart is denominated in a non-shop currency, so the catalog reads run in the same market the money does.","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"cartFingerprint":{"description":"Opaque client-supplied fingerprint of the cart state this request was built from. The engine echoes it verbatim on the result envelope so the rendering surface can compare and discard late results.","type":"string"},"placementId":{"description":"Optional at authoring time; omit it and the server fills the rule's own id when the draft is saved. Wire shape only — publish gates evaluate the rule directly, never a placement assignment, so no real placement is needed and the author should never be asked for one.","type":"string"}},"required":["surface","cart","order","pageProduct","customer","shipping"],"description":"The recommendation request the scenario evaluates. `placementId` and `surface` here are wire shape, not references: gates evaluate the rule directly, never an assignment, so no real placement is involved."},"context":{"description":"Optional evaluation context override. When absent the harness supplies a representative preview context.","type":"object","properties":{"isPreview":{"type":"boolean","description":"True when the evaluation is a preview (editor/test-lab) run rather than live traffic."},"slotsNeeded":{"type":"integer","minimum":0,"maximum":50,"description":"How many recommendation slots the placement wants filled. Non-negative integer, at most 50 — ZERO is reachable, because a placement can resolve to no slots, so a rule must answer zero with an empty envelope before it reads anything."},"excludeOutOfStock":{"default":true,"description":"The rule's out-of-stock setting. When true, every SDK catalog read and product recommendation drops products with no variant for sale, so rule code never filters stock itself. Defaults to true, the rule setting's own default. A read that passes its own `excludeOutOfStock` overrides it.","type":"boolean"}},"required":["isPreview","slotsNeeded"]},"evaluatedAt":{"description":"Optional author-pinned evaluation instant, epoch milliseconds UTC. When absent the harness stamps the publish job's own instant. Pin it to make a time-dependent scenario stable: a case like 'a 30-day supply ordered 34 days ago' needs both ends fixed, or its expected verdict drifts with the calendar.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":{"description":"Display copy for scenario pickers, phrased for a merchant (e.g. 'A cart that matches your matching cover-ups rule'). Absent on scenarios authored before display copy existed.","type":"string","maxLength":500},"targetBranchId":{"description":"The branch this scenario is designed to fire: the graph branch node id (=== the attempt() base label). Null marks the nothing-matches scenario whose cart clears no branch; absent means unannotated (typically hand-authored).","type":["string","null"]},"origin":{"description":"'authored' = written by a person or authoring agent alongside the rule; 'generated' = produced by the scenario-generation service. Regeneration replaces only 'generated' scenarios and never clobbers authored ones.","type":"string","enum":["authored","generated"]}},"required":["name","request"]}},"required":["scenario"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"envelope":{"type":"object","properties":{"version":{"type":"number","const":1,"description":"Envelope schema version. Activating any reserved shape bumps this version — consumers negotiate on it, it never breaks silently. Independent of the REST API path version."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["product","variant","image","reviewRef","metaobjectRef","bundle"],"description":"Item kind. Consumers ignore kinds they don't understand — never errors."},"id":{"type":"string","description":"Shopify GID of the recommended entity, scoped by `kind` (e.g. gid://shopify/Product/<n> for kind 'product'). For kind 'bundle' the id is the Product GID of the bundle's parent/anchor product, never a merchant-chosen key — there is no gid://shopify/Bundle/<n>."},"defaultVariantId":{"description":"Which variant is pre-selected for the shopper — the core output for product-kind items, so surfaces render a purchasable default without re-deriving one.","type":"string"},"allowedVariantIds":{"description":"Exhaustive list of variant GIDs the shopper may add, when the merchant restricted the item to a subset of its variants. ABSENT means unrestricted (every variant is allowed); present means only these are. Surfaces that mint per-variant discount signatures MUST sign only these — treating absence and an empty list alike would mint a signature for a variant the merchant excluded.","type":"array","items":{"type":"string"}},"sellingPlanId":{"description":"Shopify selling-plan GID to attach when the item is added, for subscription recommendations. RESERVED in V1.","type":"string"},"intent":{"description":"'add' adds the item to the cart. 'replace' asks the surface to swap out the originating cart line and is materialized by NO surface today — emitting it is refused at publish rather than silently downgraded, because a surface that can only Add would put the swap target alongside the item it was meant to replace. Recommend the swap target with intent 'add', or wait for a surface that supports it. RESERVED in V1.","type":"string","enum":["add","replace"]},"discount":{"description":"RESERVED in V1 and read by NO surface — setting it prices nothing, and it is REFUSED at ingress. Pricing is the placement's, never the rule's. Activating this field bumps the envelope version.","type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"],"description":"'percentage' or 'fixed'."},"value":{"type":"number","minimum":0,"description":"For 'percentage': percent points (10 = 10% off). For 'fixed': integer minor units in the shop currency."}},"required":["type","value"],"additionalProperties":false},"sourceBranch":{"description":"Path-capable label of the rule branch that produced this item (e.g. 'colour-match/size-in-stock'), for telemetry and debugging.","type":"string"},"children":{"description":"Child lines when kind is 'bundle'. Each child's `id` must match its own `kind` — a 'product' child carries a Product GID, a 'variant' child a ProductVariant GID. Schema-level tolerance: presence on other kinds is a gate concern, not a parse error.","type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["product","variant","image","reviewRef","metaobjectRef","bundle"],"description":"Kind of the child item (scopes how `id` is interpreted)."},"id":{"type":"string","description":"Shopify GID of the child, scoped by `kind`."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Units of the child included in the bundle. Positive integer."}},"required":["kind","id","quantity"],"additionalProperties":false,"description":"One child line of a bundle-kind recommendation item."}}},"required":["kind","id"],"additionalProperties":false,"description":"One recommended item. `kind` scopes how `id` is interpreted. Consumers MUST ignore kinds they do not understand — unknown kinds are never errors; the kind list exists so gates can validate rule output, not so surfaces can reject envelopes."},"description":"Recommended items in render order. An empty array is a valid result — a miss, not an error."},"branchFired":{"description":"The terminal rule branch that produced this result.","type":"object","properties":{"base":{"type":"string","description":"The literal label passed to attempt('label') in the rule source — statically lexable, so publish gates can verify it exists in the code."},"instance":{"description":"Runtime instance qualifier when one branch runs multiple passes (e.g. the tag this pass ran against). Present ONLY when the attempt supplied one via `attempt(base, fn, { instance })`; the key is omitted entirely otherwise, so consumers must treat its absence as normal and must never assert deep equality against an object that assumes it.","type":"string"}},"required":["base"],"additionalProperties":false},"cartFingerprint":{"description":"Echo of the request's cartFingerprint, verbatim. The rendering surface compares it against the current cart state and discards late results that no longer match.","type":"string"},"warnings":{"description":"Non-fatal notices from the evaluation, surfaced to telemetry and debugging tools.","type":"array","items":{"type":"string"}},"metadata":{"description":"Rule-authored metadata. Free-form and read by NOTHING — no key here is interpreted. A rule decides WHICH products are recommended; it never prices them. The discount and the struck-through price belong to the placement the rule is attached to, where the merchant sets them.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["version","items"],"additionalProperties":false,"description":"What a recommendation rule returns. Conventions: ids are Shopify GIDs; money is integer minor units with explicit ISO-4217 currency; timestamps are ISO-8601 UTC. Engine errors and timeouts collapse to an empty result behaviorally (the surface follows the placement's onEmpty policy) but stay distinct in evaluation telemetry."},"telemetry":{"type":"object","properties":{"outcome":{"type":"string","enum":["result","empty","error"],"description":"'result' = items returned; 'empty' = valid miss (zero items); 'error' = the evaluation failed or timed out and the surface fell back to empty behavior."},"errorClass":{"description":"Free-form classifier of the failure when outcome is 'error'. Deliberately not an enum yet — the vocabulary gets pinned once real failure modes exist.","type":"string"},"datasetRevisions":{"description":"The dataset revisions the evaluation's pinned reads resolved to, one entry per distinct key read. This is the field the impression stamp records (persistence lands with the impression store, M4).","type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The dataset key the evaluation read."},"revision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The revision the evaluation's pinned read resolved to."}},"required":["key","revision"],"additionalProperties":false,"description":"One resolved dataset pin of an evaluation: the key and the exact revision the evaluation read."}},"removedByExclusion":{"description":"Items removed by serving exclusions, with only the item id and the approved removal reason.","type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"reason":{"type":"string","enum":["product_id","tag","collection","vendor","metadata_unavailable"]}},"required":["itemId","reason"],"additionalProperties":false}},"attempts":{"description":"Per-attempt chain records in execution order, captured by the SDK runtime's accumulator — never authored by rule code. Fallback rate = attempt 1 contributed 0. Absent means no chain ran, never 'zero attempts'.","type":"array","items":{"type":"object","properties":{"base":{"type":"string","description":"The attempt's stable base label (e.g. 'colour-match')."},"instance":{"description":"Per-invocation instance qualifier (e.g. the seed product handle) for readout grouping. Present ONLY when the attempt supplied one via `attempt(base, fn, { instance })`; the key is omitted entirely otherwise, so consumers must treat its absence as normal and must never assert deep equality against a record that assumes it.","type":"string"},"contributed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many of this attempt's items made the final result. Non-negative integer."},"outcome":{"type":"string","enum":["contributed","empty","not-selected","skipped","error"],"description":"'contributed' | 'empty' | 'not-selected' | 'skipped' | 'error' — see AgenticLogicAttemptOutcomeList for exact semantics."}},"required":["base","contributed","outcome"],"additionalProperties":false,"description":"Telemetry record for one chain attempt. Chains emit one per attempt so readouts can show exactly which branches ran, contributed, or fell through."}},"evaluationSource":{"description":"Which lane produced this evaluation: 'serving' = a shopper-facing surface, 'api' = the metered external/MCP evaluate endpoint, 'preview' = authoring preview, 'eligibility' = a server-side check on a cart no shopper sees. 'api', 'preview' and 'eligibility' evaluations are never impressions — readouts must exclude them.","type":"string","enum":["serving","api","preview","eligibility"]},"executionTier":{"description":"Which executor ran the rule: 'template' = the shared warm template runner, 'custom' = the org's own rule Lambda. Absent when the evaluation exited before an assignment resolved, so nothing ran. Not the same vocabulary as the stored version execution kind.","type":"string","enum":["template","custom"]},"deadlineMs":{"description":"The RELATIVE time budget the evaluation ran under, in milliseconds — min(surface hard cap, the assignment's budgetMs). The absolute epoch deadline is meaningless in a readout and already rides the invocation as system.deadlineAtMs. Absent when the evaluation exited before an assignment resolved.","type":"integer","minimum":0,"maximum":9007199254740991},"fallback":{"description":"What the placement's onEmpty policy did with an empty rule result: 'not-applicable' = the rule returned items, so no policy ran; 'hidden' = onEmpty is 'hide'; 'materialized' = the smart-recs fallback supplied the items; 'unavailable' = smart-recs was asked and had nothing to give; 'failed' = the fallback read itself errored. This is what separates empties a readout would otherwise collapse into one bucket.","type":"string","enum":["not-applicable","hidden","materialized","unavailable","failed"]},"classifierBreakerTripped":{"description":"Whether the org-scoped storefront-classifier breaker was already open when this evaluation started, so the rule was short-circuited rather than executed. Absent when the evaluation exited before the breaker was consulted.","type":"boolean"}},"required":["outcome"],"additionalProperties":false,"description":"Telemetry facts for one rule evaluation. Emission is the broker's job; the shape is typed here so the vocabulary is pinned with the envelope. Errors and timeouts collapse to empty behaviorally (the surface follows the placement's onEmpty policy) but stay distinct here."}},"required":["envelope","telemetry"],"additionalProperties":false},"exclusions":{"type":"object","properties":{"evaluated":{"type":"boolean"},"removals":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"reason":{"type":"string","enum":["product_id","tag","collection","vendor","metadata_unavailable"]},"matchedValue":{"type":["string","null"]}},"required":["itemId","reason","matchedValue"],"additionalProperties":false}}},"required":["evaluated","removals"],"additionalProperties":false},"coverage":{"anyOf":[{"type":"object","properties":{"firedBranchId":{"description":"The branch node id the evaluation's branchFired telemetry names, or null when nothing matched (or the reported base names no branch node in this graph revision).","type":["string","null"]},"branchStates":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["fired","attempted","skipped"]},"description":"Per branch node id: 'fired' | 'attempted' (tried but did not fire) | 'skipped' (never reached)."},"traversedNodeIds":{"type":"array","items":{"type":"string"},"description":"Node ids on the evaluation's solid path; the renderer dims everything else."},"terminalNodeId":{"type":"string","description":"The 'output' node when the envelope carries items, the 'fallback-terminal' when it is empty."}},"required":["firedBranchId","branchStates","traversedNodeIds","terminalNodeId"],"additionalProperties":false,"description":"The join between one evaluation's branch-level telemetry and the rule's graph artifact: which branch fired, the state of every branch, and the solid path the renderer keeps undimmed."},{"type":"null"}]},"hydratedItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"variantId":{"type":["string","null"]},"title":{"type":"string"},"variantTitle":{"type":["string","null"]},"price":{"type":"string"}},"required":["id","variantId","title","price"],"additionalProperties":false}},"onEmpty":{"type":"string","enum":["hide","smart-recs"]},"evaluated":{"type":"object","properties":{"source":{"type":"string","enum":["draft","published_version","template"]},"version":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["source","version"],"additionalProperties":false},"logs":{"description":"Entries the rule's `logger` calls wrote during this run, in call order. Present for code rules, including when the rule threw or exceeded its budget; absent for builder rules and when the run failed on the platform side (for example a failed SDK read), including a throw after the rule caught a failed SDK read; a budget overrun after one still has them. When a failed run's output exceeds 256KB, only its earliest and latest entries are kept and `logsTruncated` is true. Each `timestamp` is host wall-clock time when `logger` was called, with millisecond precision, so the difference between two entries is the elapsed time between those calls.","type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["log","info","warn","error","debug"],"description":"Log level ('log' | 'info' | 'warn' | 'error' | 'debug')."},"message":{"type":"string","description":"The log message."},"details":{"description":"Optional structured details payload."},"invocationId":{"description":"Broker invocation identifier that correlates this entry with one recorded rule run.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the entry was emitted (ISO-8601 UTC)."}},"required":["level","message","timestamp"],"additionalProperties":false,"description":"One structured log entry emitted by rule code through the injected marker logger. Wire format shared with deployed bundles — append-only."}},"logsTruncated":{"description":"True when the failed run wrote more than 256KB of output, so `logs` holds only its earliest and latest entries. Absent when `logs` is complete.","type":"boolean","const":true}},"required":["result","coverage","hydratedItems","evaluated"],"additionalProperties":false,"description":"The scenario preview, plus the logger output of a code rule's run."}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Publish a rule

> \*\*Success status:\*\* 202 Accepted.\
> \
> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/publish\
> \`\`\`\
> \
> Starts an asynchronous publish job for the rule's current draft (code rules) or\
> template configuration (builder rules).\
> \
> \- \`notes\` (string, optional) — Notes stamped on the resulting version.\
> \- \`title\` (string, optional, up to 255 characters) — Display title stamped on\
> &#x20; the resulting version. When omitted, a draft that came from the AI chat gets\
> &#x20; "Built from chat" and any other draft gets no title.\
> \- \`idempotencyKey\` (string, optional) — Client-supplied key. Repeating a publish\
> &#x20; for the same rule and key returns the existing job handle instead of starting\
> &#x20; another job.\
> \- \`autoAssist\` (boolean, optional) — Whether a failed job starts AI repair.\
> &#x20; Defaults to \`true\`. Send \`false\` to leave a failed job failed (see below).\
> &#x20; It is frozen into this job only; it is not stored on the rule.\
> \
> The endpoint answers \`202 Accepted\` with \`{ "publishJobId": "..." }\`. Publishing\
> runs a gate pipeline (static checks, tests, budget and safety gates,\
> deployment) that takes seconds to minutes; poll the publish job until \`status\`\
> is \`succeeded\`, \`failed\`, or \`cancelled\`. A successful publish makes the new\
> version active immediately. A first publish moves a \`draft\` rule to \`active\`; a\
> publish never resumes a \`paused\` rule.\
> \
> \- When a code rule's draft has no validation scenarios, the checks run one\
> &#x20; default scenario: an \`onsite\` request in USD from the US, with the rule's id\
> &#x20; as the placement.\
> \- A failed publish of a code rule opens an AI repair run, unless one is already\
> &#x20; running. The repair loop rewrites the draft and re-runs the checks; when they\
> &#x20; pass, it publishes the rewritten source, unless the rewrite changed what the\
> &#x20; rule does. Follow it through \`activeRepairRun\` on\
> &#x20; \[Get a rule]\(#get-a-rule); the failed job itself stays \`failed\`.\
> \
> With \`autoAssist: false\`, a failed job opens no repair run, so the platform\
> never rewrites the rule's source or republishes it on its own. It does not stop\
> a repair run that is already running; \[cancel]\(#cancel-a-check-run) does. A\
> successful publish is unaffected.\
> \
> A repeated \`idempotencyKey\` returns the job it first started, with the\
> \`autoAssist\` value that job was started with. The \`autoAssist\` sent on the\
> repeat is ignored.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/publish":{"post":{"operationId":"publishAgenticLogicRule","summary":"Publish a rule","tags":["Agentic Logic"],"description":"**Success status:** 202 Accepted.\n\n```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/publish\n```\n\nStarts an asynchronous publish job for the rule's current draft (code rules) or\ntemplate configuration (builder rules).\n\n- `notes` (string, optional) — Notes stamped on the resulting version.\n- `title` (string, optional, up to 255 characters) — Display title stamped on\n  the resulting version. When omitted, a draft that came from the AI chat gets\n  \"Built from chat\" and any other draft gets no title.\n- `idempotencyKey` (string, optional) — Client-supplied key. Repeating a publish\n  for the same rule and key returns the existing job handle instead of starting\n  another job.\n- `autoAssist` (boolean, optional) — Whether a failed job starts AI repair.\n  Defaults to `true`. Send `false` to leave a failed job failed (see below).\n  It is frozen into this job only; it is not stored on the rule.\n\nThe endpoint answers `202 Accepted` with `{ \"publishJobId\": \"...\" }`. Publishing\nruns a gate pipeline (static checks, tests, budget and safety gates,\ndeployment) that takes seconds to minutes; poll the publish job until `status`\nis `succeeded`, `failed`, or `cancelled`. A successful publish makes the new\nversion active immediately. A first publish moves a `draft` rule to `active`; a\npublish never resumes a `paused` rule.\n\n- When a code rule's draft has no validation scenarios, the checks run one\n  default scenario: an `onsite` request in USD from the US, with the rule's id\n  as the placement.\n- A failed publish of a code rule opens an AI repair run, unless one is already\n  running. The repair loop rewrites the draft and re-runs the checks; when they\n  pass, it publishes the rewritten source, unless the rewrite changed what the\n  rule does. Follow it through `activeRepairRun` on\n  [Get a rule](#get-a-rule); the failed job itself stays `failed`.\n\nWith `autoAssist: false`, a failed job opens no repair run, so the platform\nnever rewrites the rule's source or republishes it on its own. It does not stop\na repair run that is already running; [cancel](#cancel-a-check-run) does. A\nsuccessful publish is unaffected.\n\nA repeated `idempotencyKey` returns the job it first started, with the\n`autoAssist` value that job was started with. The `autoAssist` sent on the\nrepeat is ignored.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"description":"Publish notes to stamp on the resulting version.","type":"string","minLength":1},"title":{"description":"Display title to stamp on the resulting version. When omitted, chat-origin drafts default to \"Built from chat\"; manual drafts get no title.","type":"string","minLength":1,"maxLength":255},"idempotencyKey":{"description":"Client-supplied idempotency key. A repeated publish for the same rule and key returns the existing job handle instead of starting another job.","type":"string","minLength":1},"autoAssist":{"description":"Whether a failed job starts AI repair. Defaults to true. False leaves a failed job failed: this job opens no repair loop, so it never leads the platform to rewrite or republish the rule's source. A repair loop already running for the rule is not stopped. A successful publish is unaffected. A replay of an existing idempotencyKey returns that job as it was started, whatever this says.","type":"boolean"}},"description":"Start an async publish job for the rule's current draft. Returns the job handle to poll."}}}},"responses":{"202":{"description":"Accepted","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"publishJobId":{"type":"string"}},"required":["publishJobId"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Poll a publish job

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}/publish-jobs/{jobId}\
> \`\`\`\
> \
> The response is \`{ job }\`.\
> \
> \- \`status\` is \`queued\`, \`running\`, \`succeeded\`, \`failed\`, or \`cancelled\`. A\
> &#x20; \`cancelled\` job was stopped by a person and is final.\
> \- \`mode\` is \`publish\` (every gate, then a new active version on success) or\
> &#x20; \`dry\_run\` (the validation gates only; never promotes). The API starts\
> &#x20; \`dry\_run\` jobs through \[run-gates]\(#run-the-gates-without-publishing); the\
> &#x20; platform also starts them, such as on a code rule's first draft save, in the\
> &#x20; repair loop, and from "Run tests" in the admin.\
> \- The response includes every gate with its own status and result, so a failed\
> &#x20; publish tells you which gate rejected it and why.\
> \- When a \`publish\` job succeeds, \`resultingVersionId\` identifies the version\
> &#x20; that is now active.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/publish-jobs/{jobId}":{"get":{"operationId":"getAgenticLogicRulePublishJob","summary":"Poll a publish job","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}/publish-jobs/{jobId}\n```\n\nThe response is `{ job }`.\n\n- `status` is `queued`, `running`, `succeeded`, `failed`, or `cancelled`. A\n  `cancelled` job was stopped by a person and is final.\n- `mode` is `publish` (every gate, then a new active version on success) or\n  `dry_run` (the validation gates only; never promotes). The API starts\n  `dry_run` jobs through [run-gates](#run-the-gates-without-publishing); the\n  platform also starts them, such as on a code rule's first draft save, in the\n  repair loop, and from \"Run tests\" in the admin.\n- The response includes every gate with its own status and result, so a failed\n  publish tells you which gate rejected it and why.\n- When a `publish` job succeeds, `resultingVersionId` identifies the version\n  that is now active.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true},{"in":"path","name":"jobId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string","description":"Publish-job id (uuid) — the handle returned by the publish endpoint."},"ruleId":{"type":"string","description":"Rule the job publishes (uuid)."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"'queued' | 'running' | 'succeeded' | 'failed'."},"mode":{"type":"string","enum":["publish","dry_run"],"description":"'publish' (runs every gate and promotes a version on success) | 'dry_run' (validation gates only, never promotes). What the job IS — a reader cannot infer it from status while the job is still in flight."},"startedAtTs":{"description":"Worker start time, Unix epoch-ms; null while queued.","type":["number","null"]},"finishedAtTs":{"description":"Terminal time, Unix epoch-ms; null until the job finishes.","type":["number","null"]},"resultingVersionId":{"description":"Version the job promoted, when it succeeded in publish mode; null otherwise (and null again if that version is later deleted by retention).","type":["string","null"]},"gates":{"type":"array","items":{"type":"object","properties":{"gateKey":{"type":"string","enum":["static_contract","deps_locked","org_secrets_resolved","required_tests_passed","bundle_size","runtime_timeout","chain_cost","scan_cost","graph_consistency","ai_tests_generated","ai_tests_passed","user_tests_passed","lambda_deploy"],"description":"Which gate this result belongs to."},"status":{"type":"string","enum":["pending","running","passed","failed","warning","blocked"],"description":"'pending' | 'running' | 'passed' | 'failed' | 'warning' | 'blocked'. 'warning' passes with caveats; 'blocked' means an earlier gate's failure prevented this one from running."},"result":{"description":"Human-readable gate summary, when available.","type":["string","null"]},"detailsJson":{"description":"Structured gate details, when available.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"startedAtTs":{"description":"Gate start time, Unix epoch-ms, when started.","type":["number","null"]},"finishedAtTs":{"description":"Gate finish time, Unix epoch-ms, when finished.","type":["number","null"]}},"required":["gateKey","status"],"additionalProperties":false,"description":"One gate's result within a publish job. The gate-key vocabulary is owned by the publish-gate registry; the status vocabulary is identical to the custom-shipping-provider pipeline's so workers port cleanly."},"description":"Per-gate results, in pipeline order."}},"required":["id","ruleId","status","mode","startedAtTs","finishedAtTs","resultingVersionId","gates"],"additionalProperties":false,"description":"One publish job: the async unit that runs the gate pipeline against a frozen draft snapshot and, in publish mode, promotes a new active version on success."}},"required":["job"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Run the gates without publishing

> \*\*Success status:\*\* 202 Accepted.\
> \
> \`\`\`http\
> POST /v25-10-beta/agentic-logic/rules/{ruleId}/run-gates\
> \`\`\`\
> \
> Starts an asynchronous dry run: the full publish gate set against the rule's\
> saved draft (code rules) or template configuration (builder rules), without\
> deploying. It never creates a version and never changes the rule's state, so a\
> paused rule can be checked too.\
> \
> \- \`idempotencyKey\` (string, optional) — Client-supplied key. Replays as on\
> &#x20; publish, including the \`autoAssist\` the job was started with. Keys are shared\
> &#x20; with publish: a key a publish already used returns that publish job.\
> \- \`autoAssist\` (boolean, optional) — Whether a failed dry run of a code rule\
> &#x20; starts AI repair. Defaults to \`true\`, as on publish. Send \`false\` to leave a\
> &#x20; failed job failed: no repair run opens, so the platform never rewrites the\
> &#x20; rule's source or republishes it. It does not stop a repair run that is\
> &#x20; already running. It is frozen into this job only.\
> \
> The endpoint answers \`202 Accepted\` with \`{ "publishJobId": "..." }\`. Poll it\
> with \[Poll a publish job]\(#poll-a-publish-job); its \`mode\` is \`dry\_run\`, and a\
> passing dry run ends \`succeeded\` with no \`resultingVersionId\`.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/run-gates":{"post":{"operationId":"runAgenticLogicRuleGates","summary":"Run the gates without publishing","tags":["Agentic Logic"],"description":"**Success status:** 202 Accepted.\n\n```http\nPOST /v25-10-beta/agentic-logic/rules/{ruleId}/run-gates\n```\n\nStarts an asynchronous dry run: the full publish gate set against the rule's\nsaved draft (code rules) or template configuration (builder rules), without\ndeploying. It never creates a version and never changes the rule's state, so a\npaused rule can be checked too.\n\n- `idempotencyKey` (string, optional) — Client-supplied key. Replays as on\n  publish, including the `autoAssist` the job was started with. Keys are shared\n  with publish: a key a publish already used returns that publish job.\n- `autoAssist` (boolean, optional) — Whether a failed dry run of a code rule\n  starts AI repair. Defaults to `true`, as on publish. Send `false` to leave a\n  failed job failed: no repair run opens, so the platform never rewrites the\n  rule's source or republishes it. It does not stop a repair run that is\n  already running. It is frozen into this job only.\n\nThe endpoint answers `202 Accepted` with `{ \"publishJobId\": \"...\" }`. Poll it\nwith [Poll a publish job](#poll-a-publish-job); its `mode` is `dry_run`, and a\npassing dry run ends `succeeded` with no `resultingVersionId`.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"description":"Client-supplied idempotency key. A repeated request for the same rule and key returns the existing job handle instead of starting another job; keys are shared with publish.","type":"string","minLength":1},"autoAssist":{"description":"Whether a failed dry run starts AI repair. Defaults to true. False leaves a failed job failed: this job opens no repair loop, so it never leads the platform to rewrite or republish the rule's source. A repair loop already running for the rule is not stopped. A replay of an existing idempotencyKey returns that job as it was started, whatever this says.","type":"boolean"}},"description":"Start an async dry-run job that evaluates the validation gates against the rule's current draft without publishing a version. Returns the job handle to poll."}}}},"responses":{"202":{"description":"Accepted","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"publishJobId":{"type":"string"}},"required":["publishJobId"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## List a rule's scenarios

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}/scenarios\
> \`\`\`\
> \
> Lists the validation scenarios of the rule's saved draft (code rules) or the\
> scenarios its template describes (builder rules).\
> \
> \- \`status\` is \`ready\`, or \`pending\` when the generated scenarios do not yet\
> &#x20; cover the draft's current branches. The read never starts generation.\
> \- \`branchIds\` lists the draft's \`attempt()\` branch labels, so coverage gaps are\
> &#x20; visible.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/scenarios":{"get":{"operationId":"getAgenticLogicRuleScenarios","summary":"List a rule's scenarios","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}/scenarios\n```\n\nLists the validation scenarios of the rule's saved draft (code rules) or the\nscenarios its template describes (builder rules).\n\n- `status` is `ready`, or `pending` when the generated scenarios do not yet\n  cover the draft's current branches. The read never starts generation.\n- `branchIds` lists the draft's `attempt()` branch labels, so coverage gaps are\n  visible.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable scenario name, shown in test results and gate details."},"request":{"type":"object","properties":{"surface":{"type":"string","enum":["onsite","checkout","post-purchase"],"description":"Surface the recommendation will render on. There is deliberately no 'headless' value — API callers declare the surface they render."},"placementId":{"type":"string","description":"Identifier of the placement being filled."},"cart":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","description":"ISO-4217 currency code the shopper pays in. Every money field in this cart is in it except `shopSubtotal`."},"subtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart merchandise subtotal in integer minor units of `currency`, before shipping and taxes. Do not compare it against a money threshold: thresholds are in the store's currency, so use `shopSubtotal ?? subtotal`."},"shopSubtotal":{"description":"The same subtotal converted to the store's default currency, in integer minor units of that currency. Money thresholds compare against this, so a $50 threshold means $50 whatever the shopper pays in. Equal to `subtotal` when the cart is already in the store's currency. null when the store's currency or the cart currency's exchange rate is not known yet, so no threshold can match. Absent when serving did not compute it (scenario and test carts), so read `shopSubtotal ?? subtotal`.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total unit quantity across all lines (sum of line quantities) — units, not the count of distinct lines."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"additionalProperties":false,"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"additionalProperties":false,"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"additionalProperties":false,"description":"One line in the visitor's current cart."},"description":"The cart lines."}},"required":["currency","subtotal","itemCount","lines"],"additionalProperties":false,"description":"Snapshot of the visitor's current cart. An empty cart (zero lines) is a legal cart — distinct from cart: null, which means the surface has no cart at all (post-purchase)."},{"type":"null"}],"description":"Current cart, or null when the surface has no cart (post-purchase). An empty cart is legal onsite — branch on surface, not on cart == null."},"order":{"anyOf":[{"type":"object","properties":{"orderId":{"type":"string","description":"Shopify order GID (gid://shopify/Order/<n>)."},"checkoutToken":{"description":"Shopify checkout token for the checkout that produced this order, when available.","type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Order creation time as an ISO-8601 UTC timestamp."},"currencyCode":{"type":"string","description":"ISO-4217 shop currency code the order's money fields are denominated in."},"presentmentCurrency":{"type":"string","description":"ISO-4217 currency code the shopper saw at checkout, which may differ from `currencyCode`."},"itemsSubtotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Merchandise subtotal after line-level discounts but before order-level discounts, shipping, and taxes. Integer minor units."},"discountTotal":{"description":"Total order-level discount amount in integer minor units, when any.","type":"integer","minimum":0,"maximum":9007199254740991},"shippingTotal":{"description":"Shipping charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"taxTotal":{"description":"Taxes charged in integer minor units, when known.","type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"What the shopper was actually charged, in integer minor units."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID (gid://shopify/Product/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"variantId":{"type":"string","description":"Shopify variant GID (gid://shopify/ProductVariant/<n>). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of units on the line. Positive integer."},"unitPrice":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Per-unit price actually in the cart, in integer minor units of the cart's currency."},"lineTotal":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency."},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Option name as configured on the Shopify product (e.g. 'Size')."},"value":{"type":"string","description":"Selected option value (e.g. 'Medium')."}},"required":["name","value"],"additionalProperties":false,"description":"One selected product option (e.g. Size, Color) on a cart or order line."},"description":"Selected product options for the line's variant."},"isSubscriptionLine":{"type":"boolean","description":"True when the line carries a selling plan (subscription), false for a one-time purchase."},"flags":{"type":"object","properties":{"giftCard":{"description":"True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there.","type":["boolean","null"]},"syntheticGift":{"description":"True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]},"bundleChild":{"description":"True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all.","type":["boolean","null"]},"igUpsell":{"description":"True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker.","type":["boolean","null"]}},"required":["giftCard","syntheticGift","bundleChild","igUpsell"],"additionalProperties":false,"description":"Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats."},"tags":{"description":"The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags.","type":"array","items":{"type":"string"}},"collections":{"description":"Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`.","type":"array","items":{"type":"string"}},"title":{"description":"Product title at purchase time, when available.","type":"string"},"vendor":{"description":"Product vendor at purchase time, when available.","type":"string"},"productType":{"description":"Shopify product type at purchase time, when available.","type":"string"},"sellingPlanId":{"description":"Shopify selling-plan GID (gid://shopify/SellingPlan/<n>) when the line was purchased on a subscription.","type":"string"},"discountAllocations":{"description":"Line-level discount allocations applied to this line, when any.","type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Discount amount allocated to the line, in integer minor units of the order's currency."},"title":{"description":"Discount title or code as shown on the order, when available.","type":"string"}},"required":["amount"],"additionalProperties":false,"description":"One discount amount allocated to an order line."}}},"required":["productId","variantId","quantity","unitPrice","lineTotal","selectedOptions","isSubscriptionLine","flags"],"additionalProperties":false,"description":"One line on the completed order. Extends the cart-line shape with catalog metadata that is available once the order exists."},"description":"The purchased order lines."}},"required":["orderId","createdAt","currencyCode","presentmentCurrency","itemsSubtotal","total","lines"],"additionalProperties":false,"description":"The completed order a post-purchase surface is rendered against. First-class on the post-purchase surface only; null everywhere else. Deliberately carries NO customer field — the top-level request `customer` is the single customer reference."},{"type":"null"}],"description":"Completed order — first-class on the post-purchase surface only; null elsewhere."},"pageProduct":{"anyOf":[{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product GID of the product being viewed (gid://shopify/Product/<n>). The bare numeric id the Shopify admin shows is accepted and promoted to GID form on the way in; anything that is neither is rejected."},"handle":{"type":"string","description":"Shopify product handle (URL slug) of the product being viewed."},"targeting":{"description":"Theme product facts used for onsite product targeting. Null when the theme has no product data; product-targeted branches then do not match. Absent from clients that predate the field; serving then reads the facts from Shopify when the rule targets the product.","anyOf":[{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}},"inventory":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lowestVariantPrice":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tags","collectionIds","inventory","lowestVariantPrice"],"additionalProperties":false},{"type":"null"}]}},"required":["productId","handle"],"additionalProperties":false,"description":"The product a PDP placement is rendered on. Populated for onsite product-page placements only; null everywhere else."},{"type":"null"}],"description":"Product the placement's page is about — onsite PDP placements only; null everywhere else."},"customer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Shopify customer GID (gid://shopify/Customer/<n>)."},"ordersCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Number of orders this customer has placed, or null when the surface did not supply it — checkout supplies it for a verified buyer when the app's protected-customer-data grant covers it; onsite and post-purchase never do. Integer, >= 0, when present. Null-check it, or use sdk.getCustomer() for a count that does not depend on the grant."},"amountSpent":{"description":"Lifetime spend aggregate, when known.","type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Lifetime amount spent in integer minor units of `currency`."},"currency":{"type":"string","description":"ISO-4217 currency code `amount` is denominated in."}},"required":["amount","currency"],"additionalProperties":false}},"required":["id","ordersCount"],"additionalProperties":false,"description":"Minimal identified-customer context, or null for guests. PII-MINIMAL GUARANTEE: this object carries ids, counts, and money aggregates ONLY — no email, name, phone, or address field may ever be added here. That is a contract property, not a data-availability accident; richer profile data is fetched at rule runtime via sdk.getCustomer()."},{"type":"null"}],"description":"Identified customer, or null for guests."},"shipping":{"type":"object","properties":{"state":{"type":"string","enum":["resolved","assumed","not-applicable","unavailable"],"description":"'resolved' = thresholds are known facts for this visitor; 'assumed' = best-effort defaults that may be wrong, so treat them as a hint rather than a fact when steering; 'not-applicable' = the store has no shipping incentive here, and the order may not be shipping at all; 'unavailable' = the shipping facts could not be read before the serving deadline (a Shopify read failed or timed out), so no threshold field is present and nothing is known — never read it as 'no incentive'."},"currency":{"type":"string","description":"ISO-4217 currency code the threshold fields are denominated in. Always present, even when state is 'not-applicable'."},"freeShippingThreshold":{"description":"Cart subtotal at which shipping becomes free, in integer minor units — pre-resolved to the visitor's assigned variation's threshold. Absent when there is no free-shipping incentive.","type":"integer","minimum":0,"maximum":9007199254740991},"remainingToFreeShipping":{"description":"How much more the visitor must add to qualify for free shipping, in integer minor units. 0 = already qualifies; absent or null = unresolvable.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"tiers":{"description":"Tiered incentive ladder in ascending threshold order, when the store runs tiered incentives.","type":"array","items":{"type":"object","properties":{"threshold":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Cart subtotal at which this tier unlocks, in integer minor units of the shipping context's currency."},"label":{"type":"string","description":"Shopper-facing label for the tier (e.g. 'Free shipping')."}},"required":["threshold","label"],"additionalProperties":false,"description":"One rung of a tiered shipping-incentive ladder."}},"delivery":{"description":"The delivery options Shopify computed for this checkout, as observed facts rather than merchant settings. Present only at checkout, and only once Shopify has computed options (an address or a pickup selection exists); absent onsite, post-purchase, and on first render. Present under every state, including 'not-applicable' for local pickup.","type":"object","properties":{"isLocalPickup":{"type":"boolean","description":"True when every selected delivery option is a pickup option — the buyer is not shipping anything."},"selected":{"description":"The buyer's currently selected option, when exactly one delivery group has a selection. Absent before the buyer picks, and when multiple groups (a subscription plus a one-time purchase) select different options — read `options` then.","type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"required":["isPickup","selected"],"additionalProperties":false},"options":{"type":"array","items":{"type":"object","properties":{"title":{"description":"Shopper-facing option title, when Shopify reports one.","type":"string"},"isPickup":{"type":"boolean","description":"True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate."},"selected":{"type":"boolean","description":"True when this is the buyer's currently selected option in its delivery group."},"cost":{"description":"The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"ISO-4217 currency code of `cost`. Absent with it.","type":"string"},"carrierName":{"description":"Carrier presenting the option, when Shopify reports one.","type":"string"},"transitDays":{"description":"Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"required":["isPickup","selected"],"additionalProperties":false,"description":"One delivery option Shopify offered the buyer at checkout — a shipping rate or a pickup choice — in the rule envelope's minor-unit money convention. PII-MINIMAL: option facts only, never the destination."},"description":"Every option Shopify computed, flattened across delivery groups, in Shopify's order. A zero-cost non-pickup option means the buyer already qualifies for free shipping."}},"required":["isLocalPickup","options"],"additionalProperties":false}},"required":["state","currency"],"additionalProperties":false,"description":"Shipping-incentive context. Required — 'not-applicable' is expressed in-band via its state field, never by omitting the object."},"country":{"description":"OPTIONAL. ISO-3166-1 alpha-2 code of the market this request should be evaluated in, e.g. 'CA'. Omit it (or send null) and the platform evaluates in its default market, 'US'. Name it whenever the cart is denominated in a non-shop currency, so the catalog reads run in the same market the money does.","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}]},"cartFingerprint":{"description":"Opaque client-supplied fingerprint of the cart state this request was built from. The engine echoes it verbatim on the result envelope so the rendering surface can compare and discard late results.","type":"string"}},"required":["surface","placementId","cart","order","pageProduct","customer","shipping"],"additionalProperties":false,"description":"The recommendation request the scenario evaluates. `placementId` and `surface` here are wire shape, not references: gates evaluate the rule directly, never an assignment, so no real placement is involved."},"context":{"description":"Optional evaluation context override. When absent the harness supplies a representative preview context.","type":"object","properties":{"isPreview":{"type":"boolean","description":"True when the evaluation is a preview (editor/test-lab) run rather than live traffic."},"slotsNeeded":{"type":"integer","minimum":0,"maximum":50,"description":"How many recommendation slots the placement wants filled. Non-negative integer, at most 50 — ZERO is reachable, because a placement can resolve to no slots, so a rule must answer zero with an empty envelope before it reads anything."},"excludeOutOfStock":{"default":true,"description":"The rule's out-of-stock setting. When true, every SDK catalog read and product recommendation drops products with no variant for sale, so rule code never filters stock itself. Defaults to true, the rule setting's own default. A read that passes its own `excludeOutOfStock` overrides it.","type":"boolean"}},"required":["isPreview","slotsNeeded","excludeOutOfStock"],"additionalProperties":false},"evaluatedAt":{"description":"Optional author-pinned evaluation instant, epoch milliseconds UTC. When absent the harness stamps the publish job's own instant. Pin it to make a time-dependent scenario stable: a case like 'a 30-day supply ordered 34 days ago' needs both ends fixed, or its expected verdict drifts with the calendar.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":{"description":"Display copy for scenario pickers, phrased for a merchant (e.g. 'A cart that matches your matching cover-ups rule'). Absent on scenarios authored before display copy existed.","type":"string","maxLength":500},"targetBranchId":{"description":"The branch this scenario is designed to fire: the graph branch node id (=== the attempt() base label). Null marks the nothing-matches scenario whose cart clears no branch; absent means unannotated (typically hand-authored).","type":["string","null"]},"origin":{"description":"'authored' = written by a person or authoring agent alongside the rule; 'generated' = produced by the scenario-generation service. Regeneration replaces only 'generated' scenarios and never clobbers authored ones.","type":"string","enum":["authored","generated"]}},"required":["name","request"],"additionalProperties":false,"description":"One case the publish gates evaluate a rule against: the request side only. There is no read-side half — gate-time SDK reads are served live through the same broker that serves production traffic, so a scenario pins what is asked of the rule and never what the org answers. Determinism is measured rather than replayed: every scenario is invoked twice and the envelopes must match."}},"status":{"type":"string","enum":["ready","pending"]},"branchIds":{"type":"array","items":{"type":"string"}}},"required":["scenarios","status","branchIds"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## List published versions

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}/versions\
> \`\`\`\
> \
> Lists the published versions of a rule, including which one is active.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/versions":{"get":{"operationId":"getAgenticLogicRuleVersions","summary":"List published versions","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}/versions\n```\n\nLists the published versions of a rule, including which one is active.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Version row id (uuid)."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Monotonic publish number (1, 2, 3, …). Defines recency for retention."},"status":{"type":"string","enum":["active","superseded","failed"],"description":"'active' = the version the rule serves; 'superseded' = previously active; 'failed' = the publish never promoted it."},"notes":{"description":"Publish notes, when provided.","type":["string","null"]},"title":{"description":"Display title for the version (e.g. \"Built from chat\"). Explicit publish-time title when given, defaulted server-side to \"Built from chat\" for chat-origin drafts, else null.","type":["string","null"]},"origin":{"anyOf":[{"type":"string","enum":["chat","manual"]},{"type":"null"}],"description":"Provenance copied from the draft at publish time: 'chat' = built by the workspace AI chat, 'manual' = human-authored, null for versions published before provenance was recorded."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The recommendation settings frozen with this version. THE copy serving obeys — the rule row's is the editable draft of it — which is what makes a settings edit take effect at republish rather than instantly."},"templateId":{"description":"Template this version was built from, or null for a custom-code version. Frozen at publish time: repointing the rule at another template never rewrites it.","type":["string","null"]},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The template's own version at publish time, or null for a custom-code version. Says which template implementation the frozen params were validated against."},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The normalized template parameters frozen with this version, or null for a custom-code version. THE copy serving executes — the rule row's is the editable draft of them — which is why a params edit takes effect at republish rather than instantly, and why two versions of one rule are only distinguishable here."},"dependencyLockHash":{"description":"Hash of the resolved dependency lockfile, or null when the version has no locked dependencies.","type":["string","null"]},"contentFingerprint":{"description":"SHA-256 identity of the code workspace (source, user tests, generated tests). Equal draft and active-version fingerprints mean the draft has nothing to apply. Null for template rules, and for rows not yet fingerprinted.","type":["string","null"]},"shopifyApiVersion":{"anyOf":[{"type":"string","description":"The Shopify API version this rule version's queries were validated against at publish time (the app is currently on 2026-07)."},{"type":"null"}],"description":"The Shopify API version this version's queries were validated against, captured at publish time. Immutable: bumping the app's version never rewrites it, so the rule keeps serving under this pin until it is republished. Null for versions published before pins were recorded."},"publishedAtTs":{"description":"Promotion time, Unix epoch-ms; null for failed versions.","type":["number","null"]},"publishedByUserId":{"description":"User who published, or null (system publishes).","type":["string","null"]},"publishedByUser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},{"type":"null"}],"description":"Display record for the publisher, resolved at read time, or null when there is no publisher or the account no longer resolves. Readers render this; `publishedByUserId` is an identifier, never a label."},"createdAtTs":{"type":"number","description":"Row creation time, Unix epoch-ms."}},"required":["id","version","status","notes","title","origin","settings","templateId","templateVersion","templateParams","dependencyLockHash","contentFingerprint","shopifyApiVersion","publishedAtTs","publishedByUserId","publishedByUser","createdAtTs"],"additionalProperties":false,"description":"One immutable published version of a rule. Exactly one version per rule carries status 'active' (the version pointer); rollback moves the pointer, never rewrites rows."}}},"required":["versions"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Get a published version

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/rules/{ruleId}/versions/{version}\
> \`\`\`\
> \
> Gets one published version of a rule by its publish number.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/rules/{ruleId}/versions/{version}":{"get":{"operationId":"getAgenticLogicRuleVersionDetail","summary":"Get a published version","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/rules/{ruleId}/versions/{version}\n```\n\nGets one published version of a rule by its publish number.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"ruleId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true},{"in":"path","name":"version","schema":{"type":"string","pattern":"^\\d+$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"object","properties":{"version":{"type":"object","properties":{"id":{"type":"string","description":"Version row id (uuid)."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Monotonic publish number (1, 2, 3, …). Defines recency for retention."},"status":{"type":"string","enum":["active","superseded","failed"],"description":"'active' = the version the rule serves; 'superseded' = previously active; 'failed' = the publish never promoted it."},"notes":{"description":"Publish notes, when provided.","type":["string","null"]},"title":{"description":"Display title for the version (e.g. \"Built from chat\"). Explicit publish-time title when given, defaulted server-side to \"Built from chat\" for chat-origin drafts, else null.","type":["string","null"]},"origin":{"anyOf":[{"type":"string","enum":["chat","manual"]},{"type":"null"}],"description":"Provenance copied from the draft at publish time: 'chat' = built by the workspace AI chat, 'manual' = human-authored, null for versions published before provenance was recorded."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The recommendation settings frozen with this version. THE copy serving obeys — the rule row's is the editable draft of it — which is what makes a settings edit take effect at republish rather than instantly."},"templateId":{"description":"Template this version was built from, or null for a custom-code version. Frozen at publish time: repointing the rule at another template never rewrites it.","type":["string","null"]},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The template's own version at publish time, or null for a custom-code version. Says which template implementation the frozen params were validated against."},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The normalized template parameters frozen with this version, or null for a custom-code version. THE copy serving executes — the rule row's is the editable draft of them — which is why a params edit takes effect at republish rather than instantly, and why two versions of one rule are only distinguishable here."},"dependencyLockHash":{"description":"Hash of the resolved dependency lockfile, or null when the version has no locked dependencies.","type":["string","null"]},"contentFingerprint":{"description":"SHA-256 identity of the code workspace (source, user tests, generated tests). Equal draft and active-version fingerprints mean the draft has nothing to apply. Null for template rules, and for rows not yet fingerprinted.","type":["string","null"]},"shopifyApiVersion":{"anyOf":[{"type":"string","description":"The Shopify API version this rule version's queries were validated against at publish time (the app is currently on 2026-07)."},{"type":"null"}],"description":"The Shopify API version this version's queries were validated against, captured at publish time. Immutable: bumping the app's version never rewrites it, so the rule keeps serving under this pin until it is republished. Null for versions published before pins were recorded."},"publishedAtTs":{"description":"Promotion time, Unix epoch-ms; null for failed versions.","type":["number","null"]},"publishedByUserId":{"description":"User who published, or null (system publishes).","type":["string","null"]},"publishedByUser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},{"type":"null"}],"description":"Display record for the publisher, resolved at read time, or null when there is no publisher or the account no longer resolves. Readers render this; `publishedByUserId` is an identifier, never a label."},"createdAtTs":{"type":"number","description":"Row creation time, Unix epoch-ms."}},"required":["id","version","status","notes","title","origin","settings","templateId","templateVersion","templateParams","dependencyLockHash","contentFingerprint","shopifyApiVersion","publishedAtTs","publishedByUserId","publishedByUser","createdAtTs"],"additionalProperties":false,"description":"The version row."},"sourceUrl":{"description":"Presigned URL for the version's source snapshot, or null when the version stores none.","type":["string","null"]},"userTestsUrl":{"description":"Presigned URL for the user test suite snapshot, or null when none was saved.","type":["string","null"]},"generatedTestsUrl":{"description":"Presigned URL for the generated test suite snapshot, or null when none was saved.","type":["string","null"]},"dependencyLock":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Resolved lockfile: package name → exact resolved version. Empty object when the version has no dependencies."},"graph":{"anyOf":[{"type":"object","properties":{"version":{"type":"number","const":1,"description":"Graph wire-format version. Currently 1."},"nodes":{"minItems":2,"maxItems":150,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable node id, unique within the graph. For kind 'branch', MUST equal the attempt() base label (a static string literal in the code). Runtime attempt instances are drill-in data on the node, never nodes of their own."},"kind":{"type":"string","enum":["input","branch","generator","filter","sort","limit","exclusions","output","fallback-terminal"],"description":"'input' | 'branch' | 'generator' | 'filter' | 'sort' | 'limit' | 'exclusions' | 'output' | 'fallback-terminal'. Branch nodes mirror attempt() bases; pipeline kinds describe the flow inside or after a branch, while Exclusions is the platform-owned final filter."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"Short card title shown on the node."},"summary":{"description":"One plain-language sentence describing what the node does.","type":"string","maxLength":500},"branchId":{"description":"Owning branch node id, set ONLY on generator/filter/sort/limit nodes that run inside that branch; absent for shared pipeline nodes and always absent on 'input', 'branch', 'exclusions', 'output' and 'fallback-terminal' nodes — a branch never names itself.","type":"string","minLength":1,"maxLength":200},"meta":{"description":"Kind-specific structured details (e.g. generator source, aggregate itemCount + sampleItems, limit N). Aggregates belong here — never one node per item.","type":"object","properties":{"itemCount":{"description":"Aggregate count of items the node covers (e.g. a generator drawing from a 1000-product list).","type":"integer","minimum":0,"maximum":9007199254740991},"sampleItems":{"description":"Up to five representative item names for drill-in display; never the full list.","maxItems":5,"type":"array","items":{"type":"string"}},"condition":{"description":"Plain-language matching clause for branch/filter nodes, phrased for a merchant ('in stock right now', 'cart contains a tagged cover-up'). The MATCHING card body.","type":"string","maxLength":300},"conditionSubject":{"description":"Which request context a branch node's condition chip is about — 'cart' (the default when absent), 'delivery' (request.shipping.delivery: selected option, local pickup, cost, carrier, transit days), 'shipping' (gap, threshold, tiers, state), 'customer' (ordersCount, tags), 'page' (request.pageProduct), 'order' (request.order), 'time' (request.evaluatedAt). Drives the row-header sentence; absent on always-matching branches and on every non-branch node.","type":"string","enum":["cart","delivery","shipping","customer","page","order","time"]},"sortKey":{"description":"Plain-language sort criterion for sort nodes ('Best sellers'). The SORTED BY card body.","type":"string","maxLength":120},"limit":{"description":"Maximum number of items a limit node lets through. Rendered as 'UP TO n products'.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":{}}},"required":["id","kind","label"],"additionalProperties":false,"description":"One node in a rule graph. For kind 'branch' the id IS the attempt() base label lexed from the rule's code — that identity is what the graph_consistency gate and the branchFired telemetry join on."},"description":"Graph nodes, at most RULE_GRAPH_MAX_NODES. Large inputs must be aggregated into node meta, never expanded per item."},"edges":{"maxItems":400,"type":"array","items":{"type":"object","properties":{"from":{"type":"string","minLength":1,"description":"Source node id."},"to":{"type":"string","minLength":1,"description":"Target node id."},"kind":{"type":"string","enum":["flow","fallback"],"description":"'flow' = data/control flow; 'fallback' = taken when the source produced nothing (branch miss or empty output). Fallback edges may only terminate at a branch or the fallback-terminal."}},"required":["from","to","kind"],"additionalProperties":false,"description":"One directed edge in a rule graph."},"description":"Directed edges between node ids, at most RULE_GRAPH_MAX_EDGES."}},"required":["version","nodes","edges"],"additionalProperties":false,"description":"The rule's graph artifact: a renderer-agnostic node/edge description of the rule's selection logic, versioned alongside the code. Carries NO geometry — layout is computed client-side. Produced deterministically for template rules and emitted by the authoring agent for custom-code rules, then verified by the graph_consistency gate."},{"type":"null"}],"description":"The rule-graph artifact the graph_consistency gate validated for this version (custom rules) or regenerated from template params at publish time. Null for versions published before graphs existed. Renderer-ready: no geometry, layout is client-side."}},"required":["version","sourceUrl","userTestsUrl","generatedTestsUrl","dependencyLock","graph"],"additionalProperties":false,"description":"Version list row plus the artifacts it owns."}},"required":["detail"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## List Sources

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/sources\
> \`\`\`\
> \
> Lists every Source with its refresh status and the rules whose published\
> versions read it.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources":{"get":{"operationId":"listSources","summary":"List Sources","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/sources\n```\n\nLists every Source with its refresh status and the rules whose published\nversions read it.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it."},"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"],"additionalProperties":false}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"additionalProperties":false,"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}},"additionalProperties":false},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["entry","files"],"additionalProperties":false},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"summary":{"type":"string","description":"One human-readable line describing the read."},"freshMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it."},"freshMsOverride":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default."},"status":{"type":"string","enum":["warming","ready","stale","error"],"description":"warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed)."},"fetchedAt":{"description":"When the cached answer was fetched, epoch ms; null when nothing is cached.","type":["number","null"]},"lastRefreshedAt":{"description":"When the last scheduled or requested refresh finished, epoch ms; null when none has run.","type":["number","null"]},"lastRefreshStatus":{"anyOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}],"description":"Outcome of the last scheduled or requested refresh; null when none has run."},"lastError":{"description":"Why the last refresh failed; null after a successful refresh.","type":["string","null"]},"lastBuildLog":{"description":"The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.","type":["string","null"]},"lastReadAt":{"description":"When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.","type":["number","null"]},"lastUpdateTs":{"type":"number","description":"When the Source definition was last written, epoch ms."},"usedBy":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string","description":"The rule's id."},"ruleName":{"type":"string","description":"The rule's display name."}},"required":["ruleId","ruleName"],"additionalProperties":false,"description":"One published rule that reads a dataset or Source. While any exists, it cannot be deleted (and a dataset's schema cannot change incompatibly)."},"description":"Published rules whose code reads this Source. Empty means it can be deleted."}},"required":["name","description","definition","summary","freshMs","freshMsOverride","status","fetchedAt","lastRefreshedAt","lastRefreshStatus","lastError","lastBuildLog","lastReadAt","lastUpdateTs","usedBy"],"additionalProperties":false,"description":"One row of the Source listing: the Source plus the published rules that read it."}}},"required":["sources"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Validate a Source definition

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/sources/validate\
> \`\`\`\
> \
> Runs the checks a \`PUT\` of the definition would run, without storing anything.\
> \
> \- \`definition\` (object, required) — A Source definition, the same shape as the\
> &#x20; \`PUT\` body's \`definition\`.\
> \- The response is \`{ "valid": true, "warnings": \[...] }\` or\
> &#x20; \`{ "valid": false, "errors": \[...], "warnings": \[...] }\`. \`errors\` are why a\
> &#x20; \`PUT\` would answer 400; \`warnings\` never block a write.\
> \- Script Sources are checked for the \`build\` export, ESM compatibility, the\
> &#x20; sandbox source guard, and a compilable \`outputSchema\`; GraphQL Sources for\
> &#x20; an input-independent document. Other kinds have no write-time checks.\
> \- A failed check is a \`200\` with \`valid: false\`; a malformed body is a 400.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources/validate":{"post":{"operationId":"validateSource","summary":"Validate a Source definition","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/sources/validate\n```\n\nRuns the checks a `PUT` of the definition would run, without storing anything.\n\n- `definition` (object, required) — A Source definition, the same shape as the\n  `PUT` body's `definition`.\n- The response is `{ \"valid\": true, \"warnings\": [...] }` or\n  `{ \"valid\": false, \"errors\": [...], \"warnings\": [...] }`. `errors` are why a\n  `PUT` would answer 400; `warnings` never block a write.\n- Script Sources are checked for the `build` export, ESM compatibility, the\n  sandbox source guard, and a compilable `outputSchema`; GraphQL Sources for\n  an input-independent document. Other kinds have no write-time checks.\n- A failed check is a `200` with `valid: false`; a malformed body is a 400.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"]}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}}},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["files"]},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The SDK read a Source names, restricted to reads whose answer does not depend on the request: best sellers, new arrivals, in stock, one collection page, a stored GraphQL query (storefrontGraphql: `$country: CountryCode!` + `@inContext(country: $country)`, country never stored; adminGraphql: catalog/content root fields only, no customer, order or cost fields), or a script (one `source.ts` exporting `async function build(sdk)` that the platform runs on a schedule in a sandbox; its JSON return value, up to 1 MiB, is the Source's answer, read with sdk.getSourceRaw). A GraphQL Source stores ALL of its variables. A typed or GraphQL Source's answer shares the read-cache entry of the equivalent direct SDK read; a script's value has its own entry.","type":"object"}},"required":["definition"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"valid":{"type":"boolean","const":true},"warnings":{"type":"array","items":{"type":"string"}}},"required":["valid","warnings"],"additionalProperties":false},{"type":"object","properties":{"valid":{"type":"boolean","const":false},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["valid","errors","warnings"],"additionalProperties":false}],"type":"object"}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Get a Source

> \`\`\`http\
> GET /v25-10-beta/agentic-logic/sources/{name}\
> \`\`\`\
> \
> Gets one Source. \`includeCache=true\` also returns \`cachedOutputs\`, the cached\
> answer per market, without starting a read or a refresh.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources/{name}":{"get":{"operationId":"getSource","summary":"Get a Source","tags":["Agentic Logic"],"description":"```http\nGET /v25-10-beta/agentic-logic/sources/{name}\n```\n\nGets one Source. `includeCache=true` also returns `cachedOutputs`, the cached\nanswer per market, without starting a read or a refresh.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"name","schema":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$"},"required":true},{"in":"query","name":"includeCache","schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it."},"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"],"additionalProperties":false}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"additionalProperties":false,"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}},"additionalProperties":false},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["entry","files"],"additionalProperties":false},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"summary":{"type":"string","description":"One human-readable line describing the read."},"freshMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it."},"freshMsOverride":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default."},"status":{"type":"string","enum":["warming","ready","stale","error"],"description":"warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed)."},"fetchedAt":{"description":"When the cached answer was fetched, epoch ms; null when nothing is cached.","type":["number","null"]},"lastRefreshedAt":{"description":"When the last scheduled or requested refresh finished, epoch ms; null when none has run.","type":["number","null"]},"lastRefreshStatus":{"anyOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}],"description":"Outcome of the last scheduled or requested refresh; null when none has run."},"lastError":{"description":"Why the last refresh failed; null after a successful refresh.","type":["string","null"]},"lastBuildLog":{"description":"The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.","type":["string","null"]},"lastReadAt":{"description":"When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.","type":["number","null"]},"lastUpdateTs":{"type":"number","description":"When the Source definition was last written, epoch ms."}},"required":["name","description","definition","summary","freshMs","freshMsOverride","status","fetchedAt","lastRefreshedAt","lastRefreshStatus","lastError","lastBuildLog","lastReadAt","lastUpdateTs"],"additionalProperties":false,"description":"One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source."},"cachedOutputs":{"type":"array","items":{"type":"object","properties":{"market":{"type":["string","null"]},"entry":{"anyOf":[{"type":"object","properties":{"fetchedAt":{"type":"number"},"value":{}},"required":["fetchedAt","value"],"additionalProperties":false},{"type":"null"}]}},"required":["market","entry"],"additionalProperties":false}}},"required":["source"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Create or replace a Source

> \`\`\`http\
> PUT /v25-10-beta/agentic-logic/sources/{name}\
> \`\`\`\
> \
> Creates the Source or replaces it in place, and takes effect immediately.\
> \
> \- \`description\` (string, required) — What the Source reads, for authors.\
> \- \`definition\` (object, required) — What the Source reads.\
> \- \`freshMsOverride\` (number, optional) — Freshness override, within the read\
> &#x20; kind's allowed range. Omit to use the kind's default.\
> \
> A new Source, or one whose definition or freshness changed, gets an immediate\
> first refresh after the write commits. The response carries \`warnings\` the\
> author should reconsider.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources/{name}":{"put":{"operationId":"putSource","summary":"Create or replace a Source","tags":["Agentic Logic"],"description":"```http\nPUT /v25-10-beta/agentic-logic/sources/{name}\n```\n\nCreates the Source or replaces it in place, and takes effect immediately.\n\n- `description` (string, required) — What the Source reads, for authors.\n- `definition` (object, required) — What the Source reads.\n- `freshMsOverride` (number, optional) — Freshness override, within the read\n  kind's allowed range. Omit to use the kind's default.\n\nA new Source, or one whose definition or freshness changed, gets an immediate\nfirst refresh after the write commits. The response carries `warnings` the\nauthor should reconsider.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"name","schema":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}}},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"]}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}}},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["files"]},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"freshMsOverride":{"type":"integer","minimum":60000,"maximum":9007199254740991}},"required":["description","definition"]}}}},"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it."},"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"],"additionalProperties":false}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"additionalProperties":false,"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}},"additionalProperties":false},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["entry","files"],"additionalProperties":false},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"summary":{"type":"string","description":"One human-readable line describing the read."},"freshMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it."},"freshMsOverride":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default."},"status":{"type":"string","enum":["warming","ready","stale","error"],"description":"warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed)."},"fetchedAt":{"description":"When the cached answer was fetched, epoch ms; null when nothing is cached.","type":["number","null"]},"lastRefreshedAt":{"description":"When the last scheduled or requested refresh finished, epoch ms; null when none has run.","type":["number","null"]},"lastRefreshStatus":{"anyOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}],"description":"Outcome of the last scheduled or requested refresh; null when none has run."},"lastError":{"description":"Why the last refresh failed; null after a successful refresh.","type":["string","null"]},"lastBuildLog":{"description":"The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.","type":["string","null"]},"lastReadAt":{"description":"When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.","type":["number","null"]},"lastUpdateTs":{"type":"number","description":"When the Source definition was last written, epoch ms."}},"required":["name","description","definition","summary","freshMs","freshMsOverride","status","fetchedAt","lastRefreshedAt","lastRefreshStatus","lastError","lastBuildLog","lastReadAt","lastUpdateTs"],"additionalProperties":false,"description":"One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source."},"warnings":{"type":"array","items":{"type":"string"}}},"required":["source","warnings"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Delete a Source

> \`\`\`http\
> DELETE /v25-10-beta/agentic-logic/sources/{name}\
> \`\`\`\
> \
> Deletes a Source. A Source read by any rule's active version answers 409 and\
> names those rules.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources/{name}":{"delete":{"operationId":"deleteSource","summary":"Delete a Source","tags":["Agentic Logic"],"description":"```http\nDELETE /v25-10-beta/agentic-logic/sources/{name}\n```\n\nDeletes a Source. A Source read by any rule's active version answers 409 and\nnames those rules.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"name","schema":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## Refresh a Source

> \`\`\`http\
> POST /v25-10-beta/agentic-logic/sources/{name}/refresh\
> \`\`\`\
> \
> Queues a refresh of the Source's cached data. It spends the shop's Admin API\
> read budget, so it is refused (with a reason) while the budget has no headroom,\
> during a per-Source cooldown, or when a refresh is already in flight.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/sources/{name}/refresh":{"post":{"operationId":"refreshSource","summary":"Refresh a Source","tags":["Agentic Logic"],"description":"```http\nPOST /v25-10-beta/agentic-logic/sources/{name}/refresh\n```\n\nQueues a refresh of the Source's cached data. It spends the shop's Admin API\nread budget, so it is refused (with a reason) while the budget has no headroom,\nduring a per-Source cooldown, or when a refresh is already in flight.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"name","schema":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"source":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it."},"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"],"additionalProperties":false}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"additionalProperties":false,"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}},"additionalProperties":false},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["entry","files"],"additionalProperties":false},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"summary":{"type":"string","description":"One human-readable line describing the read."},"freshMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it."},"freshMsOverride":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default."},"status":{"type":"string","enum":["warming","ready","stale","error"],"description":"warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed)."},"fetchedAt":{"description":"When the cached answer was fetched, epoch ms; null when nothing is cached.","type":["number","null"]},"lastRefreshedAt":{"description":"When the last scheduled or requested refresh finished, epoch ms; null when none has run.","type":["number","null"]},"lastRefreshStatus":{"anyOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}],"description":"Outcome of the last scheduled or requested refresh; null when none has run."},"lastError":{"description":"Why the last refresh failed; null after a successful refresh.","type":["string","null"]},"lastBuildLog":{"description":"The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.","type":["string","null"]},"lastReadAt":{"description":"When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.","type":["number","null"]},"lastUpdateTs":{"type":"number","description":"When the Source definition was last written, epoch ms."}},"required":["name","description","definition","summary","freshMs","freshMsOverride","status","fetchedAt","lastRefreshedAt","lastRefreshStatus","lastError","lastBuildLog","lastReadAt","lastUpdateTs"],"additionalProperties":false,"description":"One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source."},"queued":{"type":"boolean","const":true}},"required":["source","queued"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"object","properties":{"name":{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9-]*$","description":"The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it."},"description":{"type":"string","minLength":1,"maxLength":2048,"description":"What the Source reads and what rules use it for — the text an agent reads to judge reuse."},"definition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"bestSellers"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"metric":{"description":"'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.","type":"string","enum":["units","revenue"]},"scope":{"description":"Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, in rank order (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"newArrivals"},"args":{"type":"object","properties":{"timeWindow":{"description":"'24h' | '7d' | '30d' | '90d' trailing window (default '30d').","type":"string","enum":["24h","7d","30d","90d"]},"dateField":{"description":"'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.","type":"string","enum":["created","published"]},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return, newest first (max 250)."},"excludeOutOfStock":{"description":"Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.","type":"boolean"}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"inStock"},"args":{"type":"object","properties":{"minQuantity":{"description":"Minimum total inventory quantity, inclusive (default 1).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"scope":{"description":"Collections and/or tags to restrict the read to.","type":"object","properties":{"collectionIds":{"description":"Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"tags":{"description":"Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.","minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"orderBy":{"description":"Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance","inventoryTotal"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Products to return (max 250)."}},"required":["limit"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"collectionProducts"},"args":{"type":"object","properties":{"orderBy":{"description":"Server-side sort.","type":"object","properties":{"field":{"type":"string","enum":["bestSelling","price","createdAt","title","relevance"],"description":"'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key."},"direction":{"description":"'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":250,"description":"Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan)."},"include":{"description":"Extra per-product data to fetch (explicit metafield refs).","type":"object","properties":{"collectionIds":{"description":"Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"first":{"type":"integer","exclusiveMinimum":0,"maximum":250}},"required":["first"],"additionalProperties":false}]},"metafields":{"description":"Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.","type":"array","items":{"type":"object","properties":{"namespace":{"type":"string","description":"Metafield namespace (e.g. 'custom')."},"key":{"type":"string","description":"Metafield key within the namespace."}},"required":["namespace","key"],"additionalProperties":false,"description":"Reference to one product metafield by explicit namespace and key. Metafields are read live from Shopify (never synced) and must be storefront-visible per their definition — a hidden metafield surfaces as a missing value, which the authoring flow flags."}}},"additionalProperties":false},"collectionId":{"type":"string","minLength":1,"description":"Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids."}},"required":["limit","collectionId"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"storefrontGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"adminGraphql"},"args":{"type":"object","properties":{"gql":{"type":"string","minLength":1,"maxLength":10000},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["gql","variables"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"args":{"type":"object","properties":{"workspace":{"type":"object","properties":{"entry":{"default":"source.ts","type":"string","const":"source.ts"},"files":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["entry","files"],"additionalProperties":false},"outputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}],"description":"The typed read the Source names.","type":"object"},"summary":{"type":"string","description":"One human-readable line describing the read."},"freshMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it."},"freshMsOverride":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default."},"status":{"type":"string","enum":["warming","ready","stale","error"],"description":"warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed)."},"fetchedAt":{"description":"When the cached answer was fetched, epoch ms; null when nothing is cached.","type":["number","null"]},"lastRefreshedAt":{"description":"When the last scheduled or requested refresh finished, epoch ms; null when none has run.","type":["number","null"]},"lastRefreshStatus":{"anyOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}],"description":"Outcome of the last scheduled or requested refresh; null when none has run."},"lastError":{"description":"Why the last refresh failed; null after a successful refresh.","type":["string","null"]},"lastBuildLog":{"description":"The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.","type":["string","null"]},"lastReadAt":{"description":"When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.","type":["number","null"]},"lastUpdateTs":{"type":"number","description":"When the Source definition was last written, epoch ms."}},"required":["name","description","definition","summary","freshMs","freshMsOverride","status","fetchedAt","lastRefreshedAt","lastRefreshStatus","lastError","lastBuildLog","lastReadAt","lastUpdateTs"],"additionalProperties":false,"description":"One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source."},"queued":{"type":"boolean","const":false},"notQueuedReason":{"type":"string","enum":["in_flight","no_market","admin_budget","cooldown"]}},"required":["source","queued","notQueuedReason"],"additionalProperties":false}],"type":"object"}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````

## System rules

> \`\`\`http\
> PUT /v25-10-beta/agentic-logic/system-rules/{systemKey}\
> \`\`\`\
> \
> Ensures the store's built-in rule for \`systemKey\` exists. Idempotent: the first\
> call creates the rule and enqueues its first publish; every later call returns\
> the same rule unchanged. The response carries \`rule\` and \`latestPublishJob\`,\
> which tells a still-\`draft\` rule's first version being on its way from having\
> failed.\
> \
> Use the \`intelligems-access-token\` header. The token selects the organization; do not send \`orgId\`. The organization must have Agentic Logic enabled.\
> \
> \*\*Rate Limit:\*\* 50 requests per 30s window, refilling 25 tokens every 30s.

````json
{"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Agentic Logic","description":"# Agentic Logic\n\nManage recommendation rules, drafts, published versions, Sources, placements,\nassignments, and organization exclusions. Evaluate rules and saved scenarios\nbefore use.\n\nSend your customer API key in the `intelligems-access-token` header. The key\nselects your organization. Do not send `orgId`. Agentic Logic must be enabled\nfor that organization; a disabled organization receives 404.\n\nRead and evaluate operations need the key's `read_experiments` scope. Operations\nthat change rules, drafts, publish jobs, Sources, placements, assignments, or\nexclusions need `write_experiments`. A key without the scope receives 403.\n\nCreate a rule, save its draft, validate it, and publish it. Publish and run-gates\nrequests return 202 with a `publishJobId`. Poll the rule's publish-job endpoint\nuntil the job completes. A failed validation can return 200 with `valid: false`;\ncheck the response body before you publish.\n\nAll operations share a rate limit per API key: 50 requests initially, refilling\n25 requests every 30 seconds. A rate-limited request returns 429. Use the\n`Retry-After` and `X-RateLimit-*` response headers to schedule retries."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/agentic-logic/system-rules/{systemKey}":{"put":{"operationId":"ensureAgenticLogicSystemRule","summary":"System rules","tags":["Agentic Logic"],"description":"```http\nPUT /v25-10-beta/agentic-logic/system-rules/{systemKey}\n```\n\nEnsures the store's built-in rule for `systemKey` exists. Idempotent: the first\ncall creates the rule and enqueues its first publish; every later call returns\nthe same rule unchanged. The response carries `rule` and `latestPublishJob`,\nwhich tells a still-`draft` rule's first version being on its way from having\nfailed.\n\nUse the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","parameters":[{"in":"path","name":"systemKey","schema":{"type":"string","enum":["shopify-recommendations"],"description":"Which built-in rule to ensure. The call is idempotent: the first call for a store creates the rule and enqueues its first publish, and every later call returns the same rule."},"required":true,"description":"Which built-in rule to ensure. The call is idempotent: the first call for a store creates the rule and enqueues its first publish, and every later call returns the same rule."}],"responses":{"200":{"description":"OK","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"Timing-Allow-Origin":{"schema":{"type":"string"},"description":"Allowed origin for Timing headers."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string","description":"Server-issued rule id (uuid)."},"organizationId":{"type":"string","description":"Owning organization id (uuid)."},"name":{"type":"string","description":"Merchant-facing rule name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Plain-language summary of what the rule recommends, in what order, and for which shoppers."},"managedBy":{"type":"string","enum":["builder","code"],"description":"'builder' = configured from a template (templateId + templateParams + templateVersion); 'code' = a custom-code workspace rule."},"state":{"type":"string","enum":["draft","active","paused"],"description":"Lifecycle state: draft → active → paused. Paused renders as rule-absent on serving. Retiring a rule is a hard delete, legal from any state but never while referenced."},"templateId":{"description":"Template identifier for builder rules; null for code rules.","type":["string","null"]},"templateParams":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Template parameters for builder rules, validated against the template's params schema at write time; null for code rules."},"templateVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Template artifact version the rule was configured against (echo-on-execute model); null for code rules."},"targetSurfaces":{"anyOf":[{"minItems":1,"type":"array","items":{"type":"string","enum":["onsite","checkout","post-purchase"]}},{"type":"null"}],"description":"Surfaces a code rule declares it is written for, fixed at creation and never editable; the rule may only be assigned to placements on these surfaces. Null for builder rules, whose eligibility comes from their template instead. Declared, never inferred: it states which request context the rule was written against, since a surface cannot supply data it never has (post-purchase has no cart, onsite has no customer)."},"settings":{"type":"object","properties":{"maxItems":{"default":3,"description":"Most products the rule may return, 1-10. The engine supplies it to the rule as `context.slotsNeeded` and trims the envelope to it. One bound for every surface, because one rule can serve several. A surface may still show fewer at once: the checkout block's grid paginates the returned list into a carousel, which is presentation and stays with the placement.","type":"integer","minimum":1,"maximum":10},"excludeOutOfStock":{"default":true,"description":"Drop products with no purchasable variant. Applied where the product data already is: inside the template for a builder rule, inside the generated source for a code rule, and again as a floor when the engine hydrates the result — so the setting is true on every surface rather than only the ones that remembered to pass it.","type":"boolean"},"excludeItemsInCart":{"default":true,"description":"Drop products the shopper already has in the cart. Runs before the emptiness test, so an envelope this empties falls through to `onEmpty` rather than reporting itself as a result.","type":"boolean"},"excludePdpProduct":{"default":true,"description":"Drop the product the shopper is viewing (`request.pageProduct`, PDP only). Applied inside builder templates before the item cap, so the slot backfills, and again by the engine on every rule's result. Turn it off when the viewed product belongs in the result, e.g. a bundle built around it.","type":"boolean"},"onEmpty":{"default":"hide","description":"What the slot does when the rule returns zero items: 'hide' the placement or fall back to 'smart-recs'. Errors and timeouts take the same route as a miss — there is no separate error policy — and stay distinct in telemetry.","type":"string","enum":["hide","smart-recs"]}},"required":["maxItems","excludeOutOfStock","excludeItemsInCart","excludePdpProduct","onEmpty"],"additionalProperties":false,"description":"The rule's recommendation settings — item cap, the two product exclusions, and the empty-result policy. The EDITABLE copy: serving reads the copy frozen onto the active version, so changing this changes nothing until the rule is republished."},"authoringSessionId":{"description":"Id of the AI chat session that most recently authored this rule, or null for a rule created outside a chat (and for every rule created before the association was recorded). Follows the latest authoring conversation: creating the rule sets it, and a later revision session repoints it, so the transcript the workspace loads back after a reload — including the diagnosis of a build that gave up — is the one that explains the rule's current state.","type":["string","null"]},"systemKey":{"description":"Set only on a built-in rule Intelligems provisions for every store (e.g. 'shopify-recommendations'); null or absent on every rule a merchant or Atlas created. A built-in rule is read-only: it cannot be renamed, edited, paused, resumed or deleted, and there is at most one per key per store.","anyOf":[{"type":"string","enum":["shopify-recommendations"]},{"type":"null"}]},"createdAtTs":{"type":"number","description":"Creation time, Unix epoch-ms."},"lastUpdateTs":{"type":"number","description":"Last update time, Unix epoch-ms."}},"required":["id","organizationId","name","description","managedBy","state","templateId","templateParams","templateVersion","targetSurfaces","settings","authoringSessionId","createdAtTs","lastUpdateTs"],"additionalProperties":false,"description":"The store's built-in rule for this key."},"latestPublishJob":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Publish-job id (uuid) — the handle returned by the publish endpoint."},"ruleId":{"type":"string","description":"Rule the job publishes (uuid)."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"description":"'queued' | 'running' | 'succeeded' | 'failed'."},"mode":{"type":"string","enum":["publish","dry_run"],"description":"'publish' (runs every gate and promotes a version on success) | 'dry_run' (validation gates only, never promotes). What the job IS — a reader cannot infer it from status while the job is still in flight."},"startedAtTs":{"description":"Worker start time, Unix epoch-ms; null while queued.","type":["number","null"]},"finishedAtTs":{"description":"Terminal time, Unix epoch-ms; null until the job finishes.","type":["number","null"]},"resultingVersionId":{"description":"Version the job promoted, when it succeeded in publish mode; null otherwise (and null again if that version is later deleted by retention).","type":["string","null"]},"gates":{"type":"array","items":{"type":"object","properties":{"gateKey":{"type":"string","enum":["static_contract","deps_locked","org_secrets_resolved","required_tests_passed","bundle_size","runtime_timeout","chain_cost","scan_cost","graph_consistency","ai_tests_generated","ai_tests_passed","user_tests_passed","lambda_deploy"],"description":"Which gate this result belongs to."},"status":{"type":"string","enum":["pending","running","passed","failed","warning","blocked"],"description":"'pending' | 'running' | 'passed' | 'failed' | 'warning' | 'blocked'. 'warning' passes with caveats; 'blocked' means an earlier gate's failure prevented this one from running."},"result":{"description":"Human-readable gate summary, when available.","type":["string","null"]},"detailsJson":{"description":"Structured gate details, when available.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"startedAtTs":{"description":"Gate start time, Unix epoch-ms, when started.","type":["number","null"]},"finishedAtTs":{"description":"Gate finish time, Unix epoch-ms, when finished.","type":["number","null"]}},"required":["gateKey","status"],"additionalProperties":false,"description":"One gate's result within a publish job. The gate-key vocabulary is owned by the publish-gate registry; the status vocabulary is identical to the custom-shipping-provider pipeline's so workers port cleanly."},"description":"Per-gate results, in pipeline order."}},"required":["id","ruleId","status","mode","startedAtTs","finishedAtTs","resultingVersionId","gates"],"additionalProperties":false,"description":"One publish job: the async unit that runs the gate pipeline against a frozen draft snapshot and, in publish mode, promotes a new active version on success."},{"type":"null"}],"description":"The rule's most recent publish job, or null when none has been recorded. While the rule is still `draft` this is what says whether its first version is on the way or failed."}},"required":["rule","latestPublishJob"],"additionalProperties":false}}}},"429":{"description":"Too Many Requests","headers":{"access-control-allow-origin":{"schema":{"type":"string"},"description":"CORS allow-origin header."},"access-control-allow-credentials":{"schema":{"type":"string"},"description":"CORS allow-credentials header."},"content-type":{"schema":{"type":"string"},"description":"Response content type."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp (ms) when the rate limit resets."},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying after a rate limit hit."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["error","message"]}}}}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.intelligems.io/developer-resources/external-api/agentic-logic.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
