Parámetros de consulta comunes

Los endpoints de listado de WEEGLOO (los GET que devuelven una colección, como GET /spaces/{spaceId}/contents) aceptan parámetros de consulta comunes. Con estos parámetros limitas cuántos elementos devuelve una página, defines el criterio de ordenación, traes recursos relacionados en la misma respuesta, seleccionas solo los campos que necesitas, acotas la lista mediante condiciones y avanzas a la página siguiente o anterior.

Estos parámetros se comportan igual con independencia del tipo de recurso. La referencia de cada recurso describe solo las condiciones propias de ese recurso y remite a esta página para los parámetros comunes que se tratan aquí.

Parámetros

Los tipos de campos sys que se usan en order y select se pueden consultar en Propiedades del sistema (sys).

Filtro

Las condiciones de filtro no se envuelven en filter[], sino que se envían directamente como parámetros de consulta. El formato es {campo}[{operador}]={valor} y, si omites el operador, se interpreta como eq. Para ver el conjunto completo de operadores disponibles, consulta Operadores más abajo.

{campo}[{operador}]={valor}

Por ejemplo, para obtener solo los elementos cuyo name empieza por Vaso, envía name[prefix]=Vaso. Las reglas y advertencias son las siguientes.

• No envuelvas las condiciones en filter[]. Envolverlas como en filter[name[prefix]]=Vaso no funciona.
• Varias condiciones se combinan con AND. Solo quedan los elementos que las cumplen todas; no se admite la búsqueda OR, en la que basta con cumplir una de varias condiciones. Para que un mismo campo coincida con uno de varios valores, usa in.
• Una condición fields. incluye el locale. Por ejemplo, fields.file.ko-KR.mimeGroups=Image deja solo los archivos de imagen en una lista de Media, y sys.createdAt[gte]=2026-06-01T00:00:00Z deja solo los elementos creados después de ese momento.
• Para filtrar u ordenar una lista de Content por una condición fields., también hay que indicar el Content Type. Debes enviar también sys.contentType.sys.id (solo en la lista plana /contents); un simple contentType= no lo sustituye. Para más detalles, consulta la referencia de Content.

Operadores

Los campos RichText y Json no admiten búsqueda, por lo que no se pueden usar en condiciones de filtro.

Búsqueda avanzada (Advanced Search)

Los operadores regex, near y within y la búsqueda de texto completo funcionan solo en la búsqueda avanzada. La búsqueda avanzada se activa añadiendo la cabecera X-Weegloo-Advanced-Search: true a una petición de listado, y la respuesta incluye esa misma cabecera.

• Búsqueda de texto completo: cuando usas eq en un campo de texto (LongText) que tiene habilitada la búsqueda de texto completo, no solo encuentra los valores exactamente iguales, sino también los elementos que contienen ese valor, mediante coincidencia parcial y aproximada. Si la búsqueda avanzada no está activada, o si tu plan no ofrece búsqueda avanzada, ese mismo eq funciona como coincidencia exacta.
• Búsqueda por Location: near (radio) y within (polígono) solo se aplican a campos Location y solo funcionan en la búsqueda avanzada.
• Si envías regex, near o within en una petición que no puede usar la búsqueda avanzada, no se aceptan.

Paginación (cursor)

El cuerpo de una respuesta de listado contiene un objeto links, y dentro de él están next y prev. links.next es la ruta completa a la página siguiente.

/v1/spaces/HnQ32YiH/contents?limit=15&next=<cursor>

Hay dos formas de obtener la página siguiente. Puedes llamar directamente a la ruta de links.next, o puedes extraer el valor del cursor next de links.next y pasarlo como parámetro next en tu siguiente petición. Si no hay links.next, es la última página. A la página anterior se llega de la misma manera con links.prev.

Al pasar de página, no aumentes skip. Si se añaden o eliminan elementos entre una llamada al listado y otra, la posición de skip se desajusta y pueden perderse o duplicarse elementos. El cursor (next, prev) no tiene este problema.

El siguiente es un ejemplo de la estructura de una respuesta de listado. El sys.type del envoltorio es TotalPageResponse, items contiene el array de elementos y links contiene las rutas de navegación.

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount es el número total de elementos que cumplen las condiciones, y limit es el tamaño de página aplicado a esta respuesta. items contiene solo los elementos que pertenecen a esa página.

Documentos relacionados

• Propiedades del sistema (sys): los campos sys que se usan en order y select.
• Convenciones: tipo de medio, JSON Patch y concurrencia.