Read records

Previous value: -"When true, also return the TOTAL number of matching records ($count=true), ignoring top/skip. The response shape becomes { total, value } instead of a bare array.\n💡 For a COUNT-ONLY question (\"how many opportunities does X have\"), set count:true AND top:0 — you get { total: N, value: [] } in one request instead of fetching rows. Filter the same way as a normal read (e.g. lookups via ContactId → auto Contact/Id)."New value: +"Also return the total number of matching rows (ignoring top/skip): the response becomes { total, value }."

Previous value: -"Creatio OData entity set to query (e.g., Contact, Account, Activity). Tip: call \"list-entities\" first, then \"describe-entity\" to confirm fields before reading."New value: +"Entity (object schema) name, e.g. \"Contact\", \"Account\", \"Opportunity\", \"Activity\"."

Previous value: -"Structured filters (alternative to raw $filter). Handles OData syntax, GUID formatting, and lookup navigation automatically.\n\n🔗 FILTERING BY A LOOKUP (related record) — use NAVIGATION, not the scalar FK:\n- By name (best): Contact/Name eq 'Andrew Baker', Type/Name eq 'Employee'\n- By id: Contact/Id eq <guid>  (GUID, no quotes)\n- ❌ Do NOT filter the scalar `ContactId`/`OwnerId`/`AccountId` directly — Creatio OData 500s with \"Column by path XxxId not found in schema\".\n- The primary key `Id eq <guid>` DOES work as-is (it is a real column, not a lookup).\n(With this structured parameter you can pass either form — a `XxxId` field with a GUID value is auto-rewritten to `Xxx/Id`.)\n\nExamples:\n- Lookup by name: { all:[{ field:'Contact/Name', op:'eq', value:'Andrew Baker' }] } (RECOMMENDED)\n- Lookup by id: { all:[{ field:'ContactId', op:'eq', value:'60733efc-f36b-1410-a883-16d83cab0980' }] }  // becomes Contact/Id eq <guid>\n- Multiple AND: { all:[{ field:'IsActive', op:'eq', value:true }, { field:'Name', op:'contains', value:'John' }] }\n- Multiple OR: { any:[{ field:'Stage/Name', op:'eq', value:'Presentation' }, { field:'Stage/Name', op:'eq', value:'Negotiation' }] }"New value: +"Structured filter: { all: [...], any: [...] } of { field, op, value } or { field, in: [...] }. Examples: { all: [{ field: \"Account.Name\", op: \"eq\", value: \"Acme\" }] }; { all: [{ field: \"OwnerId\", op: \"eq\", value: \"<contactId>\" }, { field: \"Amount\", op: \"gt\", value: 1000 }] }; { any: [{ field: \"Stage.Name\", op: \"eq\", value: \"Presentation\" }, { field: \"Stage.Name\", op: \"eq\", value: \"Negotiation\" }] }."

Previous value: -"All conditions (AND). Example: [{ field:\"Stage/Name\", op:\"eq\", value:\"Presentation\" }]"New value: +"Conditions that must ALL hold (AND)."

Previous value: -[
-  {
-    "properties": {
-      "field": {
-        "description": "Field to filter on. To filter by a linked record, use navigation: by name `Contact/Name` / `Type/Name`, or by id `Contact/Id`. A scalar lookup FK (`ContactId`, `OwnerId`, `AccountId`) with a GUID value is auto-rewritten to `<Lookup>/Id`. The primary key is `Id`.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "op": {
-        "description": "Comparison operators: eq, ne, gt, ge, lt, le, contains, startswith, endswith.",
-        "enum": [
-          "eq",
-          "ne",
-          "gt",
-          "ge",
-          "lt",
-          "le",
-          "contains",
-          "startswith",
-          "endswith"
-        ],
-        "type": "string"
-      },
-      "value": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "number"
-          },
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Value to compare with. GUIDs are emitted unquoted for Id/lookup paths; other strings are quoted/escaped automatically."
-      }
-    },
-    "required": [
-      "field",
-      "op",
-      "value"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "field": {
-        "description": "Field to filter on. To filter by a linked record, use navigation: by name `Contact/Name` / `Type/Name`, or by id `Contact/Id`. A scalar lookup FK (`ContactId`, `OwnerId`, `AccountId`) with a GUID value is auto-rewritten to `<Lookup>/Id`. The primary key is `Id`.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "in": {
-        "description": "Set of values (expanded to an OR group). Lookup FK GUIDs are auto-navigated.",
-        "items": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "number"
-            },
-            {
-              "type": "boolean"
-            }
-          ]
-        },
-        "minItems": 1,
-        "type": "array"
-      }
-    },
-    "required": [
-      "field",
-      "in"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "field": {
+        "description": "A column (`Name`), a lookup by id (`AccountId` compared with a GUID) or a related column by path (`Account.Name`). The primary key is `Id`.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "op": {
+        "description": "eq, ne, gt, ge, lt, le; contains / startswith / endswith for text (case-insensitive).",
+        "enum": [
+          "eq",
+          "ne",
+          "gt",
+          "ge",
+          "lt",
+          "le",
+          "contains",
+          "startswith",
+          "endswith"
+        ],
+        "type": "string"
+      },
+      "value": {
+        "description": "Value to compare with: text, number, boolean, a GUID for ids, or null with eq / ne for \"is empty\" / \"is not empty\". Quoting and escaping are handled for you.",
+        "type": [
+          "string",
+          "number",
+          "boolean",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "field",
+      "op",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "field": {
+        "description": "A column (`Name`), a lookup by id (`AccountId` compared with a GUID) or a related column by path (`Account.Name`). The primary key is `Id`.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "in": {
+        "description": "Matches any of these values (one value type per list).",
+        "items": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "field",
+      "in"
+    ],
+    "type": "object"
+  }
+]

Previous value: -"Any condition (OR). Example: [{ field:\"Type/Name\", op:\"eq\", value:\"Employee\" }, { field:\"Type/Name\", op:\"eq\", value:\"Manager\" }]"New value: +"Conditions of which at least ONE must hold (OR); combined with `all` by AND."

Previous value: -[
-  {
-    "properties": {
-      "field": {
-        "description": "Field to filter on. To filter by a linked record, use navigation: by name `Contact/Name` / `Type/Name`, or by id `Contact/Id`. A scalar lookup FK (`ContactId`, `OwnerId`, `AccountId`) with a GUID value is auto-rewritten to `<Lookup>/Id`. The primary key is `Id`.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "op": {
-        "description": "Comparison operators: eq, ne, gt, ge, lt, le, contains, startswith, endswith.",
-        "enum": [
-          "eq",
-          "ne",
-          "gt",
-          "ge",
-          "lt",
-          "le",
-          "contains",
-          "startswith",
-          "endswith"
-        ],
-        "type": "string"
-      },
-      "value": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "number"
-          },
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Value to compare with. GUIDs are emitted unquoted for Id/lookup paths; other strings are quoted/escaped automatically."
-      }
-    },
-    "required": [
-      "field",
-      "op",
-      "value"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "field": {
-        "description": "Field to filter on. To filter by a linked record, use navigation: by name `Contact/Name` / `Type/Name`, or by id `Contact/Id`. A scalar lookup FK (`ContactId`, `OwnerId`, `AccountId`) with a GUID value is auto-rewritten to `<Lookup>/Id`. The primary key is `Id`.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "in": {
-        "description": "Set of values (expanded to an OR group). Lookup FK GUIDs are auto-navigated.",
-        "items": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "number"
-            },
-            {
-              "type": "boolean"
-            }
-          ]
-        },
-        "minItems": 1,
-        "type": "array"
-      }
-    },
-    "required": [
-      "field",
-      "in"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "field": {
+        "description": "A column (`Name`), a lookup by id (`AccountId` compared with a GUID) or a related column by path (`Account.Name`). The primary key is `Id`.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "op": {
+        "description": "eq, ne, gt, ge, lt, le; contains / startswith / endswith for text (case-insensitive).",
+        "enum": [
+          "eq",
+          "ne",
+          "gt",
+          "ge",
+          "lt",
+          "le",
+          "contains",
+          "startswith",
+          "endswith"
+        ],
+        "type": "string"
+      },
+      "value": {
+        "description": "Value to compare with: text, number, boolean, a GUID for ids, or null with eq / ne for \"is empty\" / \"is not empty\". Quoting and escaping are handled for you.",
+        "type": [
+          "string",
+          "number",
+          "boolean",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "field",
+      "op",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "field": {
+        "description": "A column (`Name`), a lookup by id (`AccountId` compared with a GUID) or a related column by path (`Account.Name`). The primary key is `Id`.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "in": {
+        "description": "Matches any of these values (one value type per list).",
+        "items": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "field",
+      "in"
+    ],
+    "type": "object"
+  }
+]

Previous value: -"OData $orderby clause for sorting results.\n\nSyntax: \"FieldName asc\" or \"FieldName desc\"\nMultiple fields: \"Field1 asc, Field2 desc\"\n\n✅ EXAMPLES:\n- orderBy: \"Name asc\" - sort by name ascending\n- orderBy: \"CreatedOn desc\" - newest first\n- orderBy: \"Amount desc\" - highest amount first\n- orderBy: \"Name asc, Amount desc\" - sort by multiple fields\n\n⚠️ NOTE: You can only sort by direct properties of the entity.\nSorting by navigation properties (like Account/Name) is NOT supported in Creatio OData."New value: +"Sort order: \"CreatedOn desc\", \"Name asc, Amount desc\"."

Previous value: -"Fields to return from the main entity. Strongly recommended for performance.\n\n⚠️ IMPORTANT: $select works ONLY for direct properties of the entity!\n- ✅ CORRECT: select=['Id','Name','AccountId','Email']\n- ❌ WRONG: select=['Account/Name'] - navigation paths NOT supported\n\n⚠️ CRITICAL: When using $filter with $select:\n- ALWAYS include filtered fields in $select array\n- Example: filter by AccountId → select=['Id','AccountId',...]\n- Creatio returns error \"Column by path X not found\" if field filtered but not selected\n- This does NOT apply to expanded entities - those are separate\n\n💡 TO GET RELATED DATA: Use expand parameter (RECOMMENDED)!\n- expand=['Account'] loads full Account object automatically\n- No need to include expanded fields in select\n- Much better than making separate requests\n\nUse 'describe-entity' to discover available field names."New value: +"Columns to return. Recommended: keeps the response small."

Previous value: -"Offset pagination ($skip): skip this many matching rows before returning. Combine with top to page, e.g. page 3 of 25 → skip:50, top:25. Pair with a stable orderBy so pages do not overlap."New value: +"Rows to skip, for paging (page 3 of 25 → skip: 50, top: 25). Use a stable orderBy."

Previous value: -"Max rows to return ($top). Defaults to 50 when omitted (so results are never unbounded); raise it or paginate with skip for more. Use top:0 with count:true for a count-only query. Suggest 25–200."New value: +"Max rows (default 50, max 1000). With `count: true`, `top: 0` returns only the total."