Update Event Filter

Update the name, the description, or the complete definition of an existing event filter.

PATCH /api/event-criterias/:id

Updates an existing event filter. The three body fields are all optional: you can change only the name, only the description, only the definition, or any combination.

Auth: Required — event-criteria:update permission

Path Parameters

Parameter	Type	Description
`id`	UUID	Event filter ID.

Request Body

Root level (UpdateEventCriteriaDto):

Field	Type	Required	Description
`name`	string	No	New name. If sent, it cannot be empty or `null`.
`description`	string \| null	No	New description. Sending `null` clears it.
`queryBlocks`	`QueryBlockDto[]`	No	New complete definition. Minimum 1 element if sent. Replaces the existing blocks.

The structure of each block is in Definition.

`PATCH` Semantics

The PATCH is partial across fields, but total within queryBlocks. It is the distinction that decides whether an update loses blocks:

What is sent	What happens
`name` and/or `description`	Only those fields are updated. The query blocks stay intact.
`queryBlocks`	All of the filter's blocks are deleted and the ones sent are created. There is no merge by `order` or by `id`.
Nothing (body `{}`)	The filter does not change, except for `updatedBy` and `updatedAt`.

queryBlocks replaces the entire definition. Sending a single block on a filter that had three leaves the filter with one block; the other two are deleted. To modify one block you must send the complete list, including the ones that do not change.

The blocks sent are persisted as new blocks: their id are not the ones the filter had before, even if the order and the content match. A block id is not a stable identifier across updates of the definition.

On every update, updatedBy is set to the user making the request and updatedAt is refreshed.

Example

Change the name and replace the definition with one that adds a record filter over items.

curl -X PATCH https://api.reten.ai/api/event-criterias/4b8e0f15-2c76-4a03-9d58-7e1f2a3b4c5d \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ventas con ítems no-devolución",
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "event_transactions", "joins": [] },
        "select": {
          "distinct": true,
          "items": [
            { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
          ]
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "Facturada"
            },
            {
              "kind": "recordPredicate",
              "column": { "table": "event_transactions", "column": "items" },
              "subWhere": {
                "kind": "group",
                "logicalOperator": "AND",
                "children": [
                  {
                    "kind": "predicate",
                    "field": "category",
                    "comparisonOperator": "NOT_IN",
                    "value": ["devolucion"]
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }'

import axios from 'axios';

const id = '4b8e0f15-2c76-4a03-9d58-7e1f2a3b4c5d';
const body = {
  name: 'Ventas con ítems no-devolución',
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions', joins: [] },
      select: {
        distinct: true,
        items: [
          { kind: 'column', column: { table: 'event_transactions', column: 'event_id' } },
        ],
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'Facturada',
          },
          {
            kind: 'recordPredicate',
            column: { table: 'event_transactions', column: 'items' },
            subWhere: {
              kind: 'group',
              logicalOperator: 'AND',
              children: [
                {
                  kind: 'predicate',
                  field: 'category',
                  comparisonOperator: 'NOT_IN',
                  value: ['devolucion'],
                },
              ],
            },
          },
        ],
      },
    },
  ],
};

const response = await axios.patch(
  `https://api.reten.ai/api/event-criterias/${id}`,
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const updated = response.data;

Response `200 OK`

Returns the updated filter as IEventCriteriaDetail — the same shape as GET /event-criterias/:id, with the blocks already persisted and their new id.

{
  "id": "4b8e0f15-2c76-4a03-9d58-7e1f2a3b4c5d",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "name": "Ventas con ítems no-devolución",
  "description": "Ventas facturadas con al menos una línea que no es devolución",
  "isActive": true,
  "ownerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "updatedBy": "0f0e0d0c-0b0a-4090-8070-605040302010",
  "createdAt": "2026-07-12T11:05:19.220Z",
  "updatedAt": "2026-07-18T16:41:02.907Z",
  "queryBlocks": [
    {
      "id": "c8d9e0f1-2a3b-4c5d-8e6f-7a8b9c0d1e2f",
      "order": 0,
      "setOperator": null,
      "from": { "table": "event_transactions", "joins": [] },
      "select": {
        "distinct": true,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
        ]
      },
      "timeWindow": null,
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "Facturada"
          },
          {
            "kind": "recordPredicate",
            "column": { "table": "event_transactions", "column": "items" },
            "subWhere": {
              "kind": "group",
              "logicalOperator": "AND",
              "children": [
                {
                  "kind": "predicate",
                  "field": "category",
                  "comparisonOperator": "NOT_IN",
                  "value": ["devolucion"]
                }
              ]
            }
          }
        ]
      },
      "groupBy": null,
      "having": null
    }
  ]
}

Validation Rules

The definition is validated only if the body carries queryBlocks, and before touching anything: a replacement that does not compile to SQL does not delete the blocks that already existed. An update that only changes name or description does not revalidate the stored definition.

The full catalog of rules and their exact messages is in Definition → Validation Rules.

Error Responses

Status	Description
`400`	The `id` is not a valid UUID, the DTO is invalid (incorrect type, enum out of range, empty `queryBlocks`, unknown property) or a violated business rule.
`401`	Missing or invalid `Authorization: Bearer`.
`403`	The user lacks the `event-criteria:update` permission, or the `x-tenant-id` is not authorized.
`404`	No event filter exists with that `id` in the tenant (`Event criteria not found`).